The model validation rule settings for using StrengthValidator to validate an attribute are:

  • hasUser boolean check whether attribute contains the username field

  • userAttribute string name of the username attribute field. Defaults to username. This will be used to check whether username is contained in the attribute.

  • hasEmail boolean check whether password contains an email pattern

  • min int minimum number of characters. If not set, defaults to 4.

  • max int maximum length. If not set, it means no maximum length limit.

  • length int specifies the exact length that the value should be of

  • lower int minimal number of lower case characters (defaults to 2)

  • upper int minimal number of upper case characters (defaults to 2)

  • digit int minimal number of numeric / digit characters (defaults to 2)

  • special int minimal number of special characters (defaults to 2)

View a complete demo.

use kartik\password\StrengthValidator;

// Model Rules Setup
public function rules() {
    return [
        [['username', 'password'], 'required'],
        [['password'], StrengthValidator::className(), 'min'=>8, 'digit'=>0, 'special'=>3]
    ];
}

You can pass a preset, instead of setting each rule parameter for strength validation as described in the previous section.There are 5 default presets available in the presets configuration file and summarized below. You can override and create your own presets configuration. Just set the value of presetsSource to a valid path to point to your presets file.

  • StrengthValidator::SIMPLE or simple

  • StrengthValidator::NORMAL or normal

  • StrengthValidator::FAIR or fair

  • StrengthValidator::MEDIUM or medium

  • StrengthValidator::COMPLEX or Complex

NOTE: If you pass a preset, it will override any other settings you may have passed.

Example of using the MEDIUM preset is described below. Try out if each rule is valid in the password input in the form below:

StrengthValidator::MEDIUM => [
    'min' => 10,
    'upper' => 1,
    'lower' => 1,
    'digit' => 2,
    'special' => 1,
    'hasUser' => true,
    'hasEmail' => true
];

View a complete demo.

use kartik\password\StrengthValidator;
// Model Rules Setup
public function rules() {
    return [
        [['username', 'password'], 'required'],
        [['password'], StrengthValidator::className(), 'preset'=>StrengthValidator::MEDIUM]
    ];
}

Each rule validation parameter contains a validation message which is shown if the rule fails. These parameters are

  • strError: user-defined error message used when the value is not a string

  • minError: user-defined error message used when the length of the value is smaller than min

  • maxError: user-defined error message used when the length of the value is greater than max

  • lengthError: user-defined error message used when the length of the value is not equal to length

  • hasUserError: user-defined error message used when hasUser is true and value contains the username

  • hasEmailError: user-defined error message used when hasEmail is true and value contains an email pattern

  • lowerError: user-defined error message used when value contains less than lower characters

  • upperError: user-defined error message used when value contains less than upper characters

  • digitError: user-defined error message used when value contains less than digit characters

  • specialError: user-defined error message used when value contains less than special characters

NOTE: These variables will be populated automatically within each error message:
  • {attribute}: The label of the attribute being validated

  • {found}: The number of characters found for min, lower, upper, digit, special

  • {required}: The required number of characters as set in these rules

Example of using a custom rule message is described below.

View a complete demo.

use kartik\password\StrengthValidator;
// Model Rules Setup
public function rules() {
    return [
        [['username', 'password'], 'required'],
        [
            ['password'], 
            StrengthValidator::className(), 
            'min' => 5,
            'minError'=>'You entered only {found} characters. Minimum is {required}, dude.'
        ]
    ];
}