Welcome to the Cookbook

When working with associated models, it is important to realize that saving model data should always be done by the corresponding CakePHP model. If you are saving a new Post and its associated Comments, then you would use both Post and Comment models during the save operation.

If neither of the associated model records exists in the system yet (for example, you want to save a new User and their related Profile records at the same time), you'll need to first save the primary, or parent model.

To get an idea of how this works, let's imagine that we have an action in our UsersController that handles the saving of a new User and a related Profile. The example action shown below will assume that you've POSTed enough data (using the FormHelper) to create a single User and a single Profile.

<?php
function add() {
	if (!empty($this->data)) {
		// We can save the User data:
		// it should be in $this->data['User']
 
		$user = $this->User->save($this->data);

		// If the user was saved, Now we add this information to the data
		// and save the Profile.
      
		if (!empty($user)) {
			// The ID of the newly created user has been set
			// as $this->User->id.
			$this->data['Profile']['user_id'] = $this->User->id;

			// Because our User hasOne Profile, we can access
			// the Profile model through the User model:
			$this->User->Profile->save($this->data);
		}
	}
}
?>

1. <?php
2. function add() {
3. if (!empty($this->data)) {
4. // We can save the User data:
5. // it should be in $this->data['User']
7. $user = $this->User->save($this->data);
8. // If the user was saved, Now we add this information to the data
9. // and save the Profile.
11. if (!empty($user)) {
12. // The ID of the newly created user has been set
13. // as $this->User->id.
14. $this->data['Profile']['user_id'] = $this->User->id;
15. // Because our User hasOne Profile, we can access
16. // the Profile model through the User model:
17. $this->User->Profile->save($this->data);
18. }
19. }
20. }
21. ?>

As a rule, when working with hasOne, hasMany, and belongsTo associations, its all about keying. The basic idea is to get the key from one model and place it in the foreign key field on the other. Sometimes this might involve using the $id attribute of the model class after a save(), but other times it might just involve gathering the ID from a hidden input on a form that’s just been POSTed to a controller action.

To supplement the basic approach used above, CakePHP also offers a very handy method saveAll(), which allows you to validate and save multiple models in one shot. In addtion, saveAll() provides transactional support to ensure data integrity in your database (i.e. if one model fails to save, the other models will not be saved either).

For transactions to work correctly in MySQL your tables must use InnoDB engine. Remember that MyISAM tables do not support transactions.

Let's see how we can use saveAll() to save Company and Account models at the same time.

First, you need to build your form for both Company and Account models (we'll assume that Company hasMany Account).

echo $form->create('Company', array('action'=>'add'));
echo $form->input('Company.name', array('label'=>'Company name'));
echo $form->input('Company.description');
echo $form->input('Company.location');

echo $form->input('Account.0.name', array('label'=>'Account name'));
echo $form->input('Account.0.username');
echo $form->input('Account.0.email');

echo $form->end('Add');

1. echo $form->create('Company', array('action'=>'add'));
2. echo $form->input('Company.name', array('label'=>'Company name'));
3. echo $form->input('Company.description');
4. echo $form->input('Company.location');
5. echo $form->input('Account.0.name', array('label'=>'Account name'));
6. echo $form->input('Account.0.username');
7. echo $form->input('Account.0.email');
8. echo $form->end('Add');

Take a look at the way we named the form fields for the Account model. If Company is our main model saveAll() will expect the related model's (Account) data to arrive in a specific format. And having Account.0.fieldName is exactly what we need.

The above field naming is required for a hasMany association. If the association between the models is hasOne, you have to use ModelName.fieldName notation for the associated model.

Now, in our companies_controller we can create an add() action:

function add() {
   if(!empty($this->data)) {
      $this->Company->saveAll($this->data, array('validate'=>'first'));
   }
}

1. function add() {
2. if(!empty($this->data)) {
3. $this->Company->saveAll($this->data, array('validate'=>'first'));
4. }
5. }

That's all there is to it. Now our Company and Account models will be validated and saved all at the same time. A quick thing to point out here is the use of array('validate'=>'first'); this option will ensure that both of our models are validated.

This function helps you cache the count of related data. Instead of counting the records manually via find('count'), the model itself tracks any addition/deleting towards the associated $hasMany model and increases/decreases a dedicated integer field within the parent model table.

The name of the field consists of the singular model name followed by a underscore and the word "count".

my_model_count

1. my_model_count

Let's say you have a model called ImageComment and a model called Image, you would add a new INT-field to the image table and name it image_comment_count.

Here are some more examples:

Once you have added the counter field you are good to go. Activate counter-cache in your association by adding a counterCache key and set the value to true.

class Image extends AppModel {
    var $belongsTo = array(
        'ImageAlbum' => array('counterCache' => true)
    );
}

1. class Image extends AppModel {
2. var $belongsTo = array(
3. 'ImageAlbum' => array('counterCache' => true)
4. );
5. }

From now on, every time you add or remove a Image associated to ImageAlbum, the number within image_count is adjusted automatically.

If you need to specify a custom counter field, set counterCache to the name of that field:

class Image extends AppModel {
    var $belongsTo = array(
        'ImageAlbum' => array('counterCache' => 'number_of_images')
    );
}

1. class Image extends AppModel {
2. var $belongsTo = array(
3. 'ImageAlbum' => array('counterCache' => 'number_of_images')
4. );
5. }

You can also specify counterScope. It allows you to specify a simple condition which tells the model when to update (or when not to, depending on how you look at it) the counter value.

Using our Image model example, we can specify it like so:

class Image extends AppModel {
    var $belongsTo = array(
        'ImageAlbum' => array(
            'counterCache' => true,
            'counterScope' => array('Image.active' => 1) // only count if "Image" is active = 1
    ));
}

1. class Image extends AppModel {
2. var $belongsTo = array(
3. 'ImageAlbum' => array(
4. 'counterCache' => true,
5. 'counterScope' => array('Image.active' => 1) // only count if "Image" is active = 1
6. ));
7. }

Saving models that are associated by hasOne, belongsTo, and hasMany is pretty simple: you just populate the foreign key field with the ID of the associated model. Once that's done, you just call the save() method on the model, and everything gets linked up correctly.

With HABTM, you need to set the ID of the associated model in your data array. We'll build a form that creates a new tag and associates it on the fly with some recipe.

The simplest form might look something like this (we'll assume that $recipe_id is already set to something):

<?php echo $form->create('Tag');?>
    <?php echo $form->input(
        'Recipe.id', 
        array('type'=>'hidden', 'value' => $recipe_id)); ?>
    <?php echo $form->input('Tag.name'); ?>
    <?php echo $form->end('Add Tag'); ?>

1. <?php echo $form->create('Tag');?>
2. <?php echo $form->input(
3. 'Recipe.id',
4. array('type'=>'hidden', 'value' => $recipe_id)); ?>
5. <?php echo $form->input('Tag.name'); ?>
6. <?php echo $form->end('Add Tag'); ?>

In this example, you can see the Recipe.id hidden field whose value is set to the ID of the recipe we want to link the tag to.

When the save() method is invoked within the controller, it'll automatically save the HABTM data to the database.

function add() {
    
    //Save the association
    if ($this->Tag->save($this->data)) {
        //do something on success            
    }
}

1. function add() {
3. //Save the association
4. if ($this->Tag->save($this->data)) {
5. //do something on success
6. }
7. }

With the preceding code, our new Tag is created and associated with a Recipe, whose ID was set in $this->data['Recipe']['id'].

Other ways we might want to present our associated data can include a select drop down list. The data can be pulled from the model using the find('list') method and assigned to a view variable of the model name. An input with the same name will automatically pull in this data into a <select>.

// in the controller:
$this->set('tags', $this->Recipe->Tag->find('list'));

// in the view:
$form->input('tags');

1. // in the controller:
2. $this->set('tags', $this->Recipe->Tag->find('list'));
3. // in the view:
4. $form->input('tags');

A more likely scenario with a HABTM relationship would include a <select> set to allow multiple selections. For example, a Recipe can have multiple Tags assigned to it. In this case, the data is pulled out of the model the same way, but the form input is declared slightly different. The tag name is defined using the ModelName convention.

// in the controller:
$this->set('tags', $this->Recipe->Tag->find('list'));

// in the view:
$form->input('Tag');

1. // in the controller:
2. $this->set('tags', $this->Recipe->Tag->find('list'));
3. // in the view:
4. $form->input('Tag');

Using the preceding code, a multiple select drop down is created, allowing for multiple choices to automatically be saved to the existing Recipe being added or saved to the database.

What to do when HABTM becomes complicated?

By default when saving a HasAndBelongsToMany relationship, Cake will delete all rows on the join table before saving new ones. For example if you have a Club that has 10 Children associated. You then update the Club with 2 children. The Club will only have 2 Children, not 12.

Also note that if you want to add more fields to the join (when it was created or meta information) this is possible with HABTM join tables, but it is important to understand that you have an easy option.

HasAndBelongsToMany between two models is in reality shorthand for three models associated through both a hasMany and a belongsTo association.

Consider this example:

Child hasAndBelongsToMany Club

1. Child hasAndBelongsToMany Club

Another way to look at this is adding a Membership model:

Child hasMany Membership
Membership belongsTo Child, Club
Club hasMany Membership.

1. Child hasMany Membership
2. Membership belongsTo Child, Club
3. Club hasMany Membership.

These two examples are almost the exact same. They use the same amount and named fields in the database and the same amount of models. The important differences are that the "join" model is named differently and it's behavior is more predictable.

When your join table contains extra fields besides two foreign keys, in most cases its easier to make a model for the join table and setup hasMany, belongsTo associations as shown in example above instead of using HABTM association.