public function example() {
    $data = array('Project' => array('name' => 'Testproject'));
    if ($this->Project->validates($data)) {
        echo 'valid';
    } else {
        echo 'invalid';
    }
}

If you look at this snippet, it probably looks fine to you. And it is fine if you are using CakePHP 1.1. Unfortunately, in CakePHP 1.2 the behavior of this method has changed, and so the example above doesn’t work as you would expect (depending on the validation rules). For a while the parameter of Model::validates() was deprecated (see Parameter for Model::validates() is now deprecated) and caused a warning if you used it. In the meantime the parameter is back with a new meaning…

Compare the API docs for the validates() methods. First the CakePHP 1.1 docs:

/**
 * Returns true if all fields pass validation, otherwise false.
 *
 * @param array $data POST data
 * @return boolean True if there are no errors
 * @access public
 */

And now the docs for CakePHP 1.2:

/**
 * Returns true if all fields pass validation.
 *
 * @param string $options An optional array of custom options to be made available in the beforeValidate callback
 * @return boolean True if there are no errors
 * @access public
 * @link http://book.cakephp.org/view/410/Validating-Data-from-the-Controller
 */

The parameter of the method is no longer for the data you want to validate but for options for the beforeValidate() callback method. So the example from the beginning has to be changed in the following way to make it work as expected:

public function example() {
    $data = array('Project' => array('name' => 'Testproject'));
    $this->Project->create($data);
    if ($this->Project->validates()) {
        echo 'valid';
    } else {
        echo 'invalid';
    }
}

Happy baking :)

In the meantime the visibility of this private functionality has been changed to protected, i.e. it is now possible to access it from your own models.

Ok, let’s have a look at some code. We will define a “recent” find type for the Post model:

class Post extends AppModel {	
    public function __construct($id = false, $table = null, $ds = null) {
        $this->_findMethods = $this->_findMethods + array('recent' => true);
        parent::__construct($id, $table, $ds);
    }

    protected function _findRecent($state, $query, $results = array()) {
        if ($state == 'before') {
            $query['order'] = 'Post.created DESC';
            $query['limit'] = 10;
            return $query;
        } else {
            return $results;
        }
    }
}

First, we have to enable our custom find type in the constructor. I don’t know why you have to do that, because a disabled find type doesn’t make much sense to me…

The next step is to implement a protected method for our find type. The name of this method must start with “_find”, followed by the name of the find type (with the first character uppercased). It is a bit a special method, as it gets called twice per find operation: before the find is performed, and after it is performed. This also explains the first parameter, $state, which is either “before” or “after”. In the “before” state you have to prepare and return the query settings (which are passed in with the $query parameter), and in the “after” state you have the possibility to modify the results from the $results parameter.

The last step is to actually use our custom find type as shown in the following examples:

$this->Post->find('recent');
$this->Post->find('recent', array('conditions' => array('Post.published' => true)));

I’m not sure whether this approach should be really used, as the approach with overriding the find() method seems to be easier (see my earlier article Defining custom find types).

Anyway, happy baking :)

There are two possible ways: instantiating the Model class manually, or using the ClassRegistry. First the manual way, which requires a bit more work:

class ExamplesController extends AppController {
    public $uses = array();
	
    public function index() {
        App::import('Core', 'Model');
        $this->Month = new Model(false, 'months');
        $this->Month->alias = 'Month';
        $this->set('months', $this->Month->find('all'));
    }
}

In the example above we create an instance of the Model class which uses the “months” table (and we don’t set an ID, hence the “false” in the constructor). Then we have to specify the alias property (and not the name property as you may guess). Without defining this property, the result of the find statement would be as shown below (notice the “Model” key):

Array
(
    [0] => Array
        (
            [Model] => Array
                (
                    [id] => 1
                    [name] => January
                )
        )
    ...
)

The second approach uses the ClassRegistry to instantiate the Model class. The example from above can now be shortened to:

class ExamplesController extends AppController {
    public $uses = array();
	
    public function index() {
        $this->Month = ClassRegistry::init(array('class' => 'Model', 'table' => 'months', 'alias' => 'Month'));
        $this->set('months', $this->Month->find('all'));
    }
}

As I said at the beginning of this article, this was just an experiment, but maybe you come up with a practical use case for it ;-)

// app/models/example.php
class Example extends AppModel {
    public $useTable = false;

    public function doSomething() {
        // use API XY
    }
}

This works fine, the only disadvantage is that your model inherits a lot of functionality that’s of no use. To avoid that, I use in such a case what I call “pseudo models”: I place PHP classes which do not extend AppModel in the models directory. The example from above looks then like:

// app/models/example.php
class Example {
    public function doSomething() {
        // use API XY
    }
}

In the controller you can use this model like any other model (of course with the restriction that none of the methods/properties defined in AppModel and Model will be available):

$this->Example->doSomething();

Happy baking!

// in a model method
if ($this->findCount($conditions) > 0) {
    // do something
}

If you look at this example you will realize that what the code tells us is slightly different from what the intention of the code is. The code tells us something like: “if the number of records that meet the conditions is greater than 0 then do something”. But what we really want to express is: “if there are any records that meet the conditions then do something”.

Fortunately, there exists the method Model::hasAny() for this purpose (it is not a new method, but for some reason we almost never used it), and by using this method we can simplify the example from above and make it more expressive:

// in a model method
if ($this->hasAny($conditions)) {
    // do something
}

Sure, it is only a detail, but it helps to make the code a little bit more expressive.

Ok, let’s do some examples to learn more about it. We will use the following countries table:

[1] => USA
[2] => Germany
[3] => Russia
[4] => Austria
[5] => China
[6] => Switzerland

Now, we don’t want to sort them by the id, but by some “strange” order: Austria, USA, China, Russia, Switzerland, Germany. For this purpose we can use “order by field”: the first parameter is the column name and all following parameters are values of the respective column. In CakePHP it is done in the following way:

$this->Country->find('list', array('order' => array('FIELD(Country.id, 4, 1, 5, 3, 6, 2)')));

And we get the expected result:

[4] => Austria
[1] => USA
[5] => China
[3] => Russia
[6] => Switzerland
[2] => Germany

Probably more common is the scenario that you want to have certain values at the top of a list, and the other values of the list should be ordered alphabetically. If we want the German-speaking countries at the top of the list we would do:

$this->Country->find('list', array('order' => array('FIELD(Country.id, 2, 4, 6)', 'Country.name')));

or 

$this->Country->find('list', array('order' => array('FIELD(Country.name, "Germany", "Austria", "Switzerland")', 'Country.name')));

Unfortunately, this doesn’t return the expected result, the records which should be at the top are at the bottom:

[5] => China
[3] => Russia
[1] => USA
[2] => Germany
[4] => Austria
[6] => Switzerland

We can solve this “problem” by using the “DESC” keyword and changing the order of the provided values:

$this->Country->find('list', array('order' => array('FIELD(Country.id, 6, 4, 2) DESC', 'Country.name')));

or

$this->Country->find('list', array('order' => array('FIELD(Country.name, "Switzerland", "Austria", "Germany") DESC', 'Country.name')))

With those changes we get the expected result:

[2] => Germany
[4] => Austria
[6] => Switzerland
[5] => China
[3] => Russia
[1] => USA

Thanks to Tarique for mentioning “order by field” and to Abhimanyu Grover for asking the original question.

Let’s say we have an optional “nickname” field. Its value must either be empty or an alphanumeric string with a length between three and ten characters. We start with defining the validation rules:

public $validate = array('nickname' => array('length' => array('rule' => array('between', 3, 10)),
		                             'alpha' => array('rule' => array('alphaNumeric'))));

Those rules work fine. The only “problem” is that they reject an empty string as invalid. To allow an empty string we have to set the option “allowEmpty” to true. So the $validate array is now:

public $validate = array('nickname' => array('length' => array('rule' => array('between', 3, 10)),
		                             'alpha' => array('rule' => array('alphaNumeric')),
				             'allowEmpty' => true));

It looks correct, but as you might guess, it doesn’t work. An empty string still doesn’t pass the validation.

The problem is that “allowEmpty” has to be set on the first rule and not as a setting for the field. And so we have to change the $validate array to:

public $validate = array('nickname' => array('length' => array('rule' => array('between', 3, 10), 'allowEmpty' => true),
		                             'alpha' => array('rule' => array('alphaNumeric'))));

With this solution, an empty string is accepted as a valid value. It’s not really logical, but it works ;-)

boolean is self-explanatory: it validates whether a field contains a boolean value (i.e. 0, 1, “0″, “1″, false, or true). Example:

var $validate = array('is_enabled' => array('rule' => array('boolean')));

inList ensures that the respective field only contains a value from the defined array. It is case-sensitive, i.e. if you use the rule from the example below, then the value “Red” would be invalid.

var $validate = array('color' => array('rule' => array('inList', array('red', 'green', 'blue'))));

time determines whether a field contains a valid time value. It supports both the 24 hour format (e.g. 08:10:10) and the 12 hour format (e.g. 8:10:10am). The minutes and seconds are optional in both cases.

var $validate = array('starttime' => array('rule' => array('time')));

Another recent change affected View::renderElement(): it has been deprecated in favor of View::element():

$this->renderElement('my_element', array('param1' => 'a value'));

becomes

$this->element('my_element', array('param1' => 'a value'));

I don’t know why View::renderElement() was deprecated and not View::element(), as I think the method name “renderElement” is more expressive than “element”.

Anyway, happy baking :)

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 :)

One idea is to move the functionality to the AppModel. That works, but it is a dirty solution. The AppModel should contain generic functionality relevant for all models, and not functionality specific to only two models.

Another idea is to move the functionality into a class in the vendors folder and to load it with App::import(). That works fine, but if you compare this solution with elements and helpers for reusing view functionality, and with components for reusing controller functionality, it is a bit strange there is no “native” solution for models (sure, there are behaviors, but they are not designed for the kind of code reuse I described above).

Hence I think it would be useful to have model “components”, which could be realized in the same way as controller components are realized. For example:

class Example extends AppModel {
    public $components = array('X');

    public function doSomething() {
        ...
        $this->X->doSomethingElse(); // using model component
        ...
    }
}

In the longer term it would even make sense to have a unified “components” concept to replace the current concepts of components and helpers. But well, we will see what the future brings ;-)