Inspired by this feature I wrote — just for fun — a small behavior which allows you to define named finder methods (download).

Let’s say we want to define a named finder method to get the most recent posts. The code for it is quite straightforward (you can use the same options as for the built-in find method):

// in the Post model
public $actsAs = array('NamedFinder' => array('recent' => array('order' => 'Post.created DESC', 'limit' => 10)));

With this definition in place, you can then use the named finder method in the following way:

// in your controller (e.g. PostsController)
$this->Post->findRecent();

You can also combine them with “And” if you defined multiple named finders:

$this->Post->findRecentAndPublished();

I’m not sure if this behavior is really useful in practice, as it is much less powerful than the named_scope feature of Rails, and you can accomplish (almost) the same with custom model methods or by defining a custom find type…

To use the new behavior, you either have to add it to the $actsAs property of your model:

class Post extends AppModel {
    var $actsAs = array('Containable');
}

or you can attach the behavior on the fly with:

$this->Post->Behaviors->attach('Containable');

Ok, now let’s have a look at some examples. For the examples I will use the three models Post, Comment, and Tag, with the associations: Post hasMany Comments, Post hasAndBelongsToMany Tags.

If we perform a simple find all statement, then we get back all posts plus all associated records, something like:

debug($this->Post->find('all'));

[0] => Array
        (
            [Post] => Array
                (
                    [id] => 1
                    [title] => First article
                    [content] => aaa
                    [created] => 2008-05-18 00:00:00
                )
            [Comment] => Array
                (
                    [0] => Array
                        (
                            [id] => 1
                            [post_id] => 1
                            [author] => Daniel
                            [email] => dan@example.com
                            [website] => http://example.com
                            [comment] => First comment
                            [created] => 2008-05-18 00:00:00
                        )
                    [1] => Array
                        (
                            [id] => 2
                            [post_id] => 1
                            [author] => Sam
                            [email] => sam@example.net
                            [website] => http://example.net
                            [comment] => Second comment
                            [created] => 2008-05-18 00:00:00
                        )
                )
            [Tag] => Array
                (
                    [0] => Array
                        (
                            [id] => 1
                            [name] => A
                        )
                    [1] => Array
                        (
                            [id] => 2
                            [name] => B
                        )
                )
        )

But often you don’t want to get all those data, and that’s when the Containable behavior comes to the rescue.

To get only the posts, you can do the following:

$this->Post->contain();
debug($this->Post->find('all'));

or

debug($this->Post->find('all', array('contain' => false)));

or without the Containable behavior

$this->Post->recursive = -1;
debug($this->Post->find('all'));

With the contain() method resp. the “contain” option we specify from which of the associated models we want to get data. If we want to get all posts plus the associated tags (without the comments), we would do it in the following way:

$this->Post->contain('Tag'); // we could also use an array
debug($this->Post->find('all'));

or

debug($this->Post->find('all', array('contain' => 'Tag'))); // we could also use an array

or without the Containable behavior

$this->Post->unbindModel(array('hasMany' => array('Comment')));
debug($this->Post->find('all'));

As you can see, the code using the Containable behavior is much cleaner than the code without it.

But that’s not all the Containable behavior can do for you. You can also filter the data of the associated models. If you are interested in the posts and the names of the comment authors, you could write:

$this->Post->contain('Comment.author');
debug($this->Post->find('all'));

or

debug($this->Post->find('all', array('contain' => 'Comment.author')));

[0] => Array
        (
            [Post] => Array
                (
                    [id] => 1
                    [title] => First article
                    [content] => aaa
                    [created] => 2008-05-18 00:00:00
                )
            [Comment] => Array
                (
                    [0] => Array
                        (
                            [author] => Daniel
                            [post_id] => 1
                        )
                    [1] => Array
                        (
                            [author] => Sam
                            [post_id] => 1
                        )
                )
        )

As you can see, the comment arrays only contain the author plus the post_id (which is needed by Cake to map the results).

You can also filter the (comment) data by using a condition:

$this->Post->contain('Comment.author = "Daniel"');
debug($this->Post->find('all'));

or 

debug($this->Post->find('all', array('contain' => 'Comment.author = "Daniel"')));

[0] => Array
        (
            [Post] => Array
                (
                    [id] => 1
                    [title] => First article
                    [content] => aaa
                    [created] => 2008-05-18 00:00:00
                )
            [Comment] => Array
                (
                    [0] => Array
                        (
                            [id] => 1
                            [post_id] => 1
                            [author] => Daniel
                            [email] => dan@example.com
                            [website] => http://example.com
                            [comment] => First comment
                            [created] => 2008-05-18 00:00:00
                        )
                )
        )

As you can see from these examples, the Containable behavior is very powerful, and I recommend to have a look at the tests.

Anyway, it’s very cool to have this behavior in the core :)

First we create a behavior which outputs a text before a find operation is performed:

// app/models/behaviors/example.php
class ExampleBehavior extends ModelBehavior {
    private $text = 'this is an example text';

    function setUp(&$model, $config) {
        if (isset($config['text'])) {
            $this->text = $config['text'];
        }
    }

    function beforeFind(&$model, $query) {
        echo $this->text;

        return true;
    }
}

The usual way to use a behavior is to define it with the $actsAs variable in the model. For example, to use the ExampleBehavior with the Post model, we would define it in the following way:

// app/models/post.php
class Post extends AppModel {
    var $actsAs = array('Example' => array('text' => 'some text'));
}

Every time we execute a find method of the Post model, the string “some text” is echoed.

With the new methods Model::attach() and Model::detach() With having a BehaviorCollection (with the methods attach() and detach()) as a property of the model more flexible scenarios are possible (even though I can’t think of any real use cases at the moment). If we want our Post model to act as Example only temporarily, we could write the following code:

// app/models/post.php
class Post extends AppModel {
}

// action in our controller
function index() {
    $this->Post->Behaviors->attach('Example', array('text' => 'hello world'));
    $this->set('all_posts', $this->Post->find('all'));
    $this->Post->Behaviors->detach('Example');
    $this->set('first_post', $this->Post->findById(1));
}

When we perform the find(‘all’) statement, our Post model acts as Example, i.e. the specified text is echoed, whereas with the findById statement, it no longer acts as Example, and so there is no output.

Happy baking :)

Update (2008-08-14): The example now uses the methods of the BehaviorCollection object, which is a property of the model. Thanks to kabturek for the hint!