CakePHP: Recursive Finds

(a.k.a It is not a boolean)

Being so new to CakePHP, I’ve spent a lot of time in the documentation. I mean a lot of time. Contrary to popular belief, the documentation is extensive, quite good and covers most, if not all, of the topics I’ve needed help with. One thing I’ve found, though, is that the documentation has three very specific deficiencies in many cases:

  1. Often, only simple cases are covered.
  2. There are a lot of ambiguities that I’d like to see clarified.
  3. It sometimes feels fragmented. The answer I’m looking for often isn’t found in (or even linked from) one place.

Today I ran into the latter two issues when I needed to pull data from an extended model association. I have an Attraction model that has a many-to-many (hasAndBelongsToMany) relationship with an Event model. Each event takes place at a location, so my Event model belongsTo my Location model.

When doing a find ( ‘all’ ) on my Attraction model, each result included, in addition to the Attraction itself, an Event – the model directly associated with with my attraction. I wanted to be able to display Location information as well, so I looked at the recursive parameter in an effort to have find() retrieve data from the extended association.

The find() documentation really provides very little information about the recursive parameter, but there is a syntax example:

'recursive' => 1, //int

When I looked at that, I read it to be a boolean value. To me, the parameter name itself sounds boolean and the only examples I found had a value of 1, a value commonly used (though not explicitly enough for my tastes) to represent a boolean “true”. When I set the parameter to 1, though, I got exactly the same result with the same lack of Location information.

As you may have guessed, I read it wrong. The recursive parameter is really a recursionLevels parameter. Once I set the value to 2, I got information related to the models that were directly associated with the Event model which included my Location information.

This is one of those cases where the documentation isn’t wrong, but it is fragmented and it’s not always easy for new developers to find what they need easily. As I get more familiar with CakePHP, more confident that I know what I’m doing and that I’m doing things the right (read: Cake) way, I’ll do my part to help clarify the documentation where I believe it necessary, but until then I’ll make my notes here in case they can help someone else or someone else can help me.

Subscribe12 Comments on CakePHP: Recursive Finds

  1. Kevin said...

    You should also look into the containable behavior
    You specify which models you want data back from and it handles setting the recursive level itself.

  2. ADmad said...

    The manual/api/code are pretty clear about recursive being integer. You just assumed it to be boolean.

    ‘recursive’ => 1, //int (does int mean integer? No its boolean)

    Eg: find(‘all’, array( ‘conditions’ => array(‘name’ => ‘Thomas Anderson’), ‘fields’ => array(‘name’, ‘email’), ‘order’ => ‘field3 DESC’, ‘recursive’ => 2, ‘group’ => ‘type’));

    ‘recursive’ => 2 (ah even 2 is boolean)

    @var integer (crap.. again that’s boolean)

  3. ADmad said...


    Depth: -1, 0, 1, 2
    (All so ambiguous let me just assume it to be boolean)

  4. Rob Wilkerson said...

    @Kevin: Thanks. I’m aware of that behavior, but am still trying to see what the “basics” will do for me before digging into some of the more surgical capabilities.

    @ADmad: Easy there, sailor, there’s no need to get your knickers in a twist. I said I read it wrong and I explained why I read it wrong. I wrote about it simply because I thought it might be something that others new to Cake may read wrong as well.

    Because the only examples I’d seen used a “1”, it wasn’t unreasonable in my mind to think of it as a boolean. That said, I clearly didn’t scour the docs for every mention of “recursive” and I should have looked a bit more. I’m still learning the docs, too.

  5. ADmad said...

    I have no problems with you thinking it to be boolean. People make mistakes. What i didn’t appreciate was you stating like “..provides very little information about the recursive parameter..”, “..but it can be misleading to new CakePHP developers..”.

    As i pointed out all available sources regarding the recursive property clearly state its an integer. You were just too lazy to dig deeper and conveniently blamed the doc to be ambigious/misleading.

  6. Rob Wilkerson said...

    Seriously? That’s awfully sensitive.

    Look, this post was about a mistake I made after reading the docs, not a slam-the-docs post. The post outlines:

    - What I read

    - What I thought/assumed/understood

    - Why I was wrong

    Others new to Cake might make the same mistake and maybe this will help. Or maybe not and that’s okay too.

    You’re right about my use of the term “misleading”. It was a poor (and inaccurate) choice of words and I’ve adjusted the post accordingly. That said, I stand by my statements that the documentation can be improved and even added one. Here’s why I think that (using this specific scenario):

    - I was looking to retrieve information from my model

    - I looked in what I considered (and still consider) to be the obvious place, the section entitled Retrieving Your Data.

    - I saw an ambiguity (yes, I understand that the type is documented there, but I also explained what lead me to incorrectly read it as a boolean).

    - I saw no additional information about the ‘recursive’ parameter on that page nor did I see any links to other pages that might contain related information.

    - I made an assumption and tried it. That assumption turned out to be wrong, so I continued looking via other support channels.

    Being new to Cake – I’m working on my first Cake project – I don’t want to immediately go digging through the code or the documentation for an API that I’m not decently versed in just yet so I looked elsewhere. Ultimately I found the answer. Had I not, I certainly would have dug around in the code or searched a little harder, but I was fortunate enough to get my question answered before doing so.

    Saying that the docs aren’t perfect isn’t a knock on the docs or the fine folks who put in the time to create/update them. It’s a simple statement of where I think there’s room for improvement and supporting that with how I think that they can be improved.

    Feel free to disagree with that in a reasonable manner, but don’t resort to ad hominem arguments about my laziness.

  7. Daniel H. said...

    Since you obviously think that the documentation on “recursive” might be misleading … I hope you gave it a shot and tried to improve it?!

  8. Rob Wilkerson said...

    @daniel: No, not yet. I’m still working to acquire a decent comfort level with Cake. As I mentioned in the last paragraph…

    As I get more familiar with CakePHP, more confident that I know what I’m doing and that I’m doing things the right (read: Cake) way, I’ll do my part to help clarify the documentation where I believe it necessary…

  9. beeman said...

    Good post Rob, I totally agree with you. As a newcomer to CakePHP it is sometimes hard to find the right way to do the things you want. It would be helpful to have more examples.

    I’m planning on writing some howto’s in the future, when I’m more confident about my CakePHP-skills… :)

  10. artiescie said...

    CakePHP as a team is going to be sensitive about the bad docs slam. But how do bad docs happen, and how do they get fixed?

    The documenter usually has one of the most impossible jobs. He is expected to deliver the docs at the same time as the release. As if it was a construction project.

    He might be able to pull it off: – IF the big boss said the developers had to deliver up to date, working examples of every “use case”. OR failing that – IF the developer had some authority over developer time to force them to show the code working. OR failing that – IF there were effective standards that automated testing showed real world functionality and the Developer could put them together. OR failing that – IF there existed at least good coverage tests, AND they were up to date, AND the developer had enough time to go through them and put together a real example.

    Exercise for the reader: drill down in the CakePHP WIKI for code, looks like it’s there. But wait… when I click on testsuites I see an empty page with “More info will follow”. I’m getting the picture ;-)

    Again, Let’s not point fingers, work needs to be done. What’s been done was the likely near the best possible at the time. Improvement is needed.

  11. Chris said...

    Adman, daniel h.,

    Get over it. The point is that even after all the time inbetween the last post here and now, if a diligent programmer is reading the manual they are introduced to AppModel->find() in section 3.731 where the “documentation” of its options is as follows:

    ‘recursive’ => 1, //int
    ‘limit’ => n, //int
    ‘page’ => n, //int

    The diligent programmer is made to wait until to have ‘recursive’ explained to him or her, and even then, it’s mashed together with all AppModel options documentation. Regardless of how sensitive you are, this is not good documentation. There should either be better organization of section 3.7.8 or there should be links throughout all of section 3.7 to its specific definitions.

    While artiescie’s point is obviously correct, that documenters have difficult jobs, adman’s assertion that we should all stop being “just too lazy [and] dig deeper” completely invalidates all of the documenter’s hard work in making the docs accessible in the first place.

  12. Chris C2 said...

    OMG! I agree the docs ARE confusing – In most cases the examples that explain the point in questions is very basic – and for a begginner this does not help.

    Take the example of recursive finds, the example isnt that clear, well I guess it is if you read:

    however what isnt that clear is specifically what tables does the example use, but more importantly their relationships.