Loud Baking

After checking different blogs and tutorials, the bakery, API and IRC channel, it was obvious that some kind of documentation for the validation methods available in the Model was necessary. I can’t say that I will fulfill this mission but I’ll at least share what I came up with for future reference.

Here is the ‘User’ model I will be using in my example:

class User extends AppModel
{
   var $name = 'User'; //optional

   var $validate = array(
                     'username' => array(
                                       array(
                                          'allowEmpty' => false,
                                          'required' => true,
                                          'rule' => 'alphaNumeric',
                                          'message' => 'Username should only contain alpha-numeric characters.',
                                          ),
                                       array(
                                          'rule' => array('between', 3, 10),
                                          'message' => 'User should be between 3 and 10 characters long.',
                                          ),
                                       array(
                                          'rule' => 'isUnique',
                                          'message' => 'Username is already in use.',
                                          ),
                                       ),
                     'passwd' => array(
                                    'alphaNumeric' => array(
                                                         'allowEmpty' => false,
                                                         'required' => true,
                                                         'rule' => 'alphaNumeric',
                                                         'message' => 'Username should only contain alpha-numeric characters.',
                                                         ),
                                    'validLength' => array(
                                                         'rule' => array('between', 3, 10),
                                                         'message' => 'User should be between 3 and 10 characters long.',
                                                         ),
                                    ),
                     'website' => array(
                                       array(
                                          'rule' => 'url',
                                          'on' => 'update',
                                          'message' => 'Invalid URL.',
                                          ),
                                       ),
                     'agree_tos' => array(
                                       array(
                                          'allowEmpty' => false,
                                          'required' => true,
                                          'on' => 'create',
                                          ),
                                       ),
                     );

);
}

That’s a lot of validation rules, I know - I just wanted to try covering the multiple ways of using the Model->validates() method.

Like you can see, $validate is an array where keys are field names and values are rulesets.

$validate = array('fieldname'=>array('rule'=>'method','message'=>'error message to show');

By default, a ruleset is defined as follow:

$default = array(
               'rule' => 'blank',
               'message' => 'This field cannot be left blank', //or it's translation
               'allowEmpty' => null,
               'required' => null,
               'last' => false,
               'on' => null,
               );

rule: Required, string.
By order of priority, it can be a custom model method (defined in AppModel or TestModel), a Validation method or a custom regex.

message: Required, string.
Error message to associate with the invalidated field.

allowEmpty: Optional, boolean.
If set to true, field will invalidate if the following check is true: empty($data[$fieldName]) && $data[$fieldName] != '0'. If set to false, it will invalidate if isset($data[$fieldName]) && (empty($data[$fieldName]) && !is_numeric($data[$fieldName])) returns true.

required: Optional, boolean.
If set to true, field will invalidate if !isset($data[$fieldName]) returns true.

on: Optional, string.
This can be either null, create or update. It will define when to run the validation rule respectively: always, only when creating the record, only when updating the record.

last: Optional, unknown.
I couldn’t figure what this is for, most probably an unfinished feature.

When ‘allowEmpty’ or ‘required’ are set, they have priority on ‘rule’. If any of them invalidates the field, ‘rule’ will not be checked.

The names given to the different keys in the ruleset are just for better code readability and future unbinding of some rules (next paragraph). The two following snippets act exactly the same way:

   var $validate = array(
                     'passwd' => array(
                                    'alphaNumeric' => array(
                                                         'allowEmpty' => false,
                                                         'required' => true,
                                                         'rule' => 'alphaNumeric',
                                                         'message' => 'Username should only contain alpha-numeric characters.',
                                                         ),
                                    'validLength' => array(
                                                         'rule' => array('between', 3, 10),
                                                         'message' => 'User should be between 3 and 10 characters long.',
                                                         ),
                                    ),
                     );

   var $validate = array(
                     'passwd' => array(
                                    array(
                                       'allowEmpty' => false,
                                       'required' => true,
                                       'rule' => 'alphaNumeric',
                                       'message' => 'Username should only contain alpha-numeric characters.',
                                       ),
                                    array(
                                       'rule' => array('between', 3, 10),
                                       'message' => 'User should be between 3 and 10 characters long.',
                                       ),
                     );

I mentioned unbinding validation rules, but what is that? By default, Cake will run all the rules you have set in $User->validate whenever it runs $User->invalidFields() - like when saving your model with $Model->save(). What if, in certain cases (mostly admin actions), you want to skip some (or all) of the validation rules for some (or all) the fields?

There are no pre-built cake methods for doing so, even though it should be pretty obvious - maybe an enhancement in the future. For now (1.2.0.5427alpha), here is what you can add to your custom AppModel class (updated on 30th Sept. - thanks Kiger for the work you’ve done!) :

/**
	 * Unbinds validation rules.
	 *
	 * EXAMPLES:
	 * $this->User->unbindValidation('username');
	 * $this->User->unbindValidation(array('username', 'password'=>'required', 'email'=>array('valid', 'length'), 'newsletter')));
	 *
	 * @param mixed $arr
	 * @return
	 */
	function unbindValidation($arr)
	{
		if (!is_array($arr))
		{
			$arr = array_flip(array($arr));
		}

		foreach ($arr as $fieldName => $ruleSet)
		{
			// where arr=array('username'), so $ruleSet ends up containing the field name
			if (is_numeric($fieldName))
			{
				$fieldName = $ruleSet;
				if (!array_key_exists($fieldName, $this->validate))
				{
					trigger_error(sprintf(__('AppModel::unbindValidation() could not find the validation fieldname %s::$validate[%s]', true), $this->name, $fieldName), E_USER_WARNING);
					continue;
				}

				$arr[$fieldName] = array_flip(array_keys($this->validate[$fieldName]));

			}
			// where arr=array('password'=>'required') or arr=array(email'=>array('valid', 'length'))
			else
			{
				$ruleSet = (!is_array($ruleSet)) ? array_flip(array($ruleSet)) : array_flip($ruleSet);

				if (!array_key_exists($fieldName, $this->validate))
				{
					trigger_error(sprintf(__('AppModel::unbindValidation() could not find the validation fieldname %s::$validate[%s]', true), $this->name, $fieldName), E_USER_WARNING);
					continue;
				}

				foreach ($ruleSet as $rule => $data)
				{
					if (!array_key_exists($rule, $this->validate[$fieldName]))
					{
						trigger_error(sprintf(__('AppModel::unbindValidation() could not find the validation rule %s::$validate[%s][%s]', true), $this->name, $fieldName, $rule), E_USER_WARNING);
					}
				}

				$arr[$fieldName] = $ruleSet;
			}

			$this->validate[$fieldName] = array_diff_key($this->validate[$fieldName], $arr[$fieldName]);

			if (empty($this->validate[$fieldName]))
			{
				unset($this->validate[$fieldName]);
			}
		}
	}

Now you can skip some of the validation rules before saving as follow:

//skips all validation rules for username
$this->User->unbindValidation('username');

//skips the 'url' rule for website
$this->User->unbindValidation(array('website'=>'url'));

//skips the 'alphaNumeric' and 'validLength' set of rules for passwd
$this->User->unbindValidation(array('passwd'=>array('alphaNumeric','validLength')));

That’s if for now. If I learn anything new about Cake validations, I’ll make sure to post about it. In the meantime, if I have missed something, please let me know in the comments.