Some times the core validation rules provided by Yii won't satisfy all your needs, so you'll need to create your very own validation rule.
Let's say that you want to check if a user password is safe enough.
Usually you could achieve this result just by using the CRegularExpressionValidator but for the sake of this guide let's pretend that validator does not exist.
first of all in your model class you'll have to add two constants
then in your rules method you'll have to set the rule
make sure that you won't give the rule the name of an existing one, otherwise you are going to have some troubles later.
Now the only thing you need to do is create a new method inside the model, named after the validation rule you just declared.
The new method you just created accepts two arguments:
In the rule we also setted an additional parameter named strength
the value of that parameter will be inside the $params array
As you can see inside the method we are making a call to CModel::addError().
Add Error accepts two parameters: the first one is the name of the attribute that you want to display the error in your form, the second one is the actual error string you want to be displayed.
Extending this class you also can take advantage of other features, like CActiveForm::$enableClientValidation, first implemented with Yii 1.1.7 release.
Name this directory MyValidators.
Then we create our own file: passwordStrength.php
Inside this file create our CValidator class
In the class file create one attribute for each additional parameter that you want to use inside your validation rule.
CValidator will take care to populate that attribute with the parameter value all by itself.
We also created two other attributes, each containing the patterns we want to use in our preg_match function.
Now we have to override the parent abstract method validateAttribute
The method above is self explanatory i think.
Of course you could use constants in those IF, and I actually recommend it.
As you can see this method simply returns the javascript that you need to use for your validation
You could first use Yii::import in the rules method before returning the rules array, or you can just use Yii dot notation:
Easy approach: inside-model rule
The easiest way to create a new validation rule is inside the model that is going to use it.Let's say that you want to check if a user password is safe enough.
Usually you could achieve this result just by using the CRegularExpressionValidator but for the sake of this guide let's pretend that validator does not exist.
first of all in your model class you'll have to add two constants
const WEAK = 0; const STRONG = 1;
/** * @return array validation rules for model attributes. */ public function rules() { return array( array('password', 'passwordStrength', 'strength'=>self::STRONG), ); }
Now the only thing you need to do is create a new method inside the model, named after the validation rule you just declared.
/** * check if the user password is strong enough * check the password against the pattern requested * by the strength parameter * This is the 'passwordStrength' validator as declared in rules(). */ public function passwordStrength($attribute,$params) { if ($params['strength'] === self::WEAK) $pattern = '/^(?=.*[a-zA-Z0-9]).{5,}$/'; elseif ($params['strength'] === self::STRONG) $pattern = '/^(?=.*\d(?=.*\d))(?=.*[a-zA-Z](?=.*[a-zA-Z])).{5,}$/'; if(!preg_match($pattern, $this->$attribute)) $this->addError($attribute, 'your password is not strong enough!'); }
- $attribute = is the name of the attribute that the method is validating
- $params = additional parameters that you could define in the rules
In the rule we also setted an additional parameter named strength
the value of that parameter will be inside the $params array
As you can see inside the method we are making a call to CModel::addError().
Add Error accepts two parameters: the first one is the name of the attribute that you want to display the error in your form, the second one is the actual error string you want to be displayed.
Complete approach: extending the CValidator class
If you need your custom validation rule in more then one model the best thing to do is extending the CValidator class.Extending this class you also can take advantage of other features, like CActiveForm::$enableClientValidation, first implemented with Yii 1.1.7 release.
Creating the class file
The first thing that you have to do is create your class file. The best thing is to always name it after your class name, to best use Yii lazy loading feature. Let's create a new directory inside your application extensions directory (which is located inside the protected directory).Name this directory MyValidators.
Then we create our own file: passwordStrength.php
Inside this file create our CValidator class
class passwordStrength extends CValidator { public $strength; private $weak_pattern = '/^(?=.*[a-zA-Z0-9]).{5,}$/'; private $strong_pattern = '/^(?=.*\d(?=.*\d))(?=.*[a-zA-Z](?=.*[a-zA-Z])).{5,}$/'; ...
CValidator will take care to populate that attribute with the parameter value all by itself.
We also created two other attributes, each containing the patterns we want to use in our preg_match function.
Now we have to override the parent abstract method validateAttribute
/** * Validates the attribute of the object. * If there is any error, the error message is added to the object. * @param CModel $object the object being validated * @param string $attribute the attribute being validated */ protected function validateAttribute($object,$attribute) { // check the strength parameter used in the validation rule of our model if ($this->strength == 'weak') $pattern = $this->weak_pattern; elseif ($this->strength == 'strong') $pattern = $this->strong_pattern; // extract the attribute value from it's model object $value=$object->$attribute; if(!preg_match($pattern, $value)) { $this->addError($object,$attribute,'your password is too weak!'); } }
Of course you could use constants in those IF, and I actually recommend it.
Implementing Client Validation
If you want to implement client validation you'll need to override another method inside your class: clientValidateAttribute/** * Returns the JavaScript needed for performing client-side validation. * @param CModel $object the data object being validated * @param string $attribute the name of the attribute to be validated. * @return string the client-side validation script. * @see CActiveForm::enableClientValidation */ public function clientValidateAttribute($object,$attribute) { // check the strength parameter used in the validation rule of our model if ($this->strength == 'weak') $pattern = $this->weak_pattern; elseif ($this->strength == 'strong') $pattern = $this->strong_pattern; $condition="!value.match({$pattern})"; return " if(".$condition.") { messages.push(".CJSON::encode('your password is too weak, you fool!')."); } "; }
Last step: how to use your validation class inside the module rules
There are several approach you can use here.You could first use Yii::import in the rules method before returning the rules array, or you can just use Yii dot notation:
/** * @return array validation rules for model attributes. */ public function rules() { return array( array('password', 'ext.MyValidators.passwordStrength', 'strength'=>self::STRONG), ); }
These quick