When Containable is available for our models, we can add a setting to the find operation called contain. In that setting we specify, in an array-based hierarchy, the associated data we want returned. A special value contain can receive is false, or an empty array, which tells Containable not to return any associated data.

For example, to get the first Person record without associated data, we simply do:

$person = $this->Person->find('first', array(
'contain' => false
));

If we want to obtain the first Person record together with the Family they belong to, we do:

$person = $this->Person->find('first', array(
'contain' => array('Family')
));

Using our sample data, the above query will result in the following array structure:

array(
'Person' => array(
'id' => '1',
'family_id' => '1',
'name' => 'John Doe',
'email' => 'john.doe@example.com'
),
'Family' => array(
'id' => '1',
'name' => 'The Does'
)
)

Let's say that now we also want to obtain all Post records for the person and all members in the family that Person belongs to. We would then have to do:

$person = $this->Person->find('first', array(
'contain' => array(
'Family.Person'
'Post'
)
));

The above would result in the following array structure (the created and modified fields have been removed for readability):

array(
'Person' => array(
'id' => '1',
'family_id' => '1',
'name' => 'John Doe',
'email' => 'john.doe@example.com'
),
'Family' => array(
'id' => '1',
'name' => 'The Does',
'Person' => array(
array(
'id' => '1',
'family_id' => '1',
'name' => 'John Doe',
'email' => 'john.doe@example.com'
),
array(
'id' => '2',
'family_id' => '1',
'name' => 'Jane Doe',
'email' => 'jane.doe@example.com'
)
)
),
'Post' => array(
array(
'id' => '1',
'person_id' => '1',
'title' => 'John\'s Post 1',
'body' => 'Body for John\'s Post 1'
),
array(
'id' => '2',
'person_id' => '1',
'title' => 'John\'s Post 2',
'body' => 'Body for John\'s Post 2'
)
)
)

We can also use Containable to specify which fields from a related model we want to fetch. Using the preceding sample, let's limit the Post fields so we only return the title and the Person records for the person's Family, so we only return the name field. We do so by adding the name of the field to the associated model hierarchy:

$person = $this->Person->find('first', array(
'contain' => array(
'Family.Person.name',
'Post.title'
)
));

The returned data structure will then look like this:

array(
'Person' => array(
'id' => '1',
'family_id' => '1',
'name' => 'John Doe',
'email' => 'john.doe@example.com'
),
'Family' => array(
'id' => '1',
'name' => 'The Does',
'Person' => array(
array(
'name' => 'John Doe',
'family_id' => '1',
'id' => '1'
),
array(
'name' => 'Jane Doe',
'family_id' => '1',
'id' => '2'
)
)
),
'Post' => array(
array(
'title' => 'John\'s Post 1',
'id' => '1',
'person_id' => '1'
),
array(
'title' => 'John\'s Post 2',
'id' => '2',
'person_id' => '1'
)
)
)

You may notice that even when we indicated specific fields for the Family => Person binding, and for the Post binding, there are some extra fields being returned. Those fields (such as family_id) are needed by CakePHP, and known as foreign key fields, to fetch the associated data, so Containable is smart enough to include them in the query.

Let us say that we also want a person's e-mail. As there is more than a field needed, we will need to use the array notation, using the fields setting to specify the list of fields:

$person = $this->Person->find('first', array(
'contain' => array(
'Family' => array(
'Person' => array(
'fields' => array('email', 'name')
)
),
'Post.title'
)
));

We use the contain find setting to specify what type of containment we want to use for the find operation. That containment is given as an array, where the array hierarchy mimics that of the model relationships. As the hierarchy can get deep enough to make array notation complex to deal with, the dot notation used throughout this recipe serves as an useful and more readable alternative.

If we want to refer to the model Person that belongs to the model Family, the proper contain syntax for that is Person => Family (we can also use Person.Family, which is more concise.)

We also use the fields setting to specify which fields we want fetched for a binding. We do that by specifying an array of field names as part of the binding Containable setting.

Containable looks for the contain find setting right before we issue a find operation on a model. If it finds one, it alters the model bindings to be returned by issuing unbindModel() calls on the appropriate models to unbind those relationships that are not specified in the contain find setting. It then sets the recursive find setting to the minimum value required to fetch the associated data.

Let us use a practical example to further understand this wrapping process. Using our Person model (which has a belongsTo relationship to Family, a hasOne relationship to Profile, and a hasMany relationship to Post), the following Containable based query:

$person = $this->Person->find('first', array( 'contain' => array('Family.Person') ));

or the same query using array notation:

$person = $this->Person->find('first', array( 'contain' => array('Family' => 'Person') ));

is equivalent to the following set of instructions, which do not use Containable, but the built in unbindModel() method available in CakePHP's Model class:

$this->Person->unbindModel(array( 'hasOne' => array('Profile'), 'hasMany' => array('Post') )); $person = $this->Person->find('first', array( 'recursive' => 2 ));

Not using Containable is not only much more complicated, but can also pose a problem if we decide to alter some of our relationships. In the preceding example, if we decide to remove the Profile binding, or change its relationship type, we would have to modify the unbindModel() call. However, if we are using Containable, the same code applies, without us having to worry about such changes.

Format of the contain find parameter

We have seen how to use the contain find parameter to limit which bindings are returned after a find operation. Even when its format seems self-explanatory, let us go through another example to have a deeper understanding of Containable's array notation. Assume that we have the models and relationships shown in the following diagram:

Transforming that diagram to something the Containable behavior understands is as simple as writing it using an array structure. For example, if we are issuing a find operation on the User model and we want to refer to the Profile relationship, a simple array('Profile') expression would suffice, as the Profile model is directly related to the User model.

If we want to refer to the Comment relationship for the Article records the User is an owner of, which belongs to an Article that itself belongs to our User model, then we add another dimension to the structure, which is now represented as array('Article' => 'Comment').

We can already deduce how the next example will look like. Assume we want to obtain the Comment together with the Profile of the User that commented on each Article. The structure will then look like: array('Article' => array('Comment' => array('User' => 'Profile'))).

Sometimes we want to simplify the readability, and fortunately the Containable behavior allows the above expression to be rewritten as array('Article.Comment.User.Profile'), which is known as dot notation. However, if you want to change other parameters to the binding, then this syntax would have to be changed to the full array-based expression (see section See also in this recipe).

$person = $this->Person->find('first', array(
'contain' => array(
'reset' => false,
'Family'
)
));
// ...
$this->Person->resetBindings();

$this->Person->contain(array('Family'), false);
$person = $this->Person->find('first');
// ...
$this->Person->resetBindings();