Custom validators for Zend_Form_Element

I am checking out Zend_Form from the Zend Framework these days and on my way to work today I wrote a custom validator that checks if an element has the same value as other elements in the form (typically used to confirm a password or an email address).

This “tutorial” contains quite a lot of code and requires some understanding of how Zend Framework works and how OOP works in PHP5.

My “register user” form consists of four elements:

• Email
• Confirm email
• Password
• Confirm password

All elements are required and I have attached the EmailAddress validator to the two email elements to ensure correct addresses. The thing I also want to do is to ensure that the two email elements have the same value. The same goes for the two password elements. To do this I had to write a custom validator for these cases. A similar validator can be found in the Zend_Form docs but I wanted to be able to specify the names of the element(s) an element must be equal to when I add the validator instead of hardcoding them in the validator classes (like the example in the docs does).

The form class looks a little something like this:

<?php
require_once 'Zend/Form.php';

class FKK_RegisterUserForm extends Zend_Form {
    public function init() {
        /* Set the action and method. The action is generated using the view's url helper */
        $this->setAction($this->getView()->url(array(), 'User_Register'));
        $this->setMethod('post');

        $mail = new FKK_Form_Element_Text('mail');
        $mail->setLabel('Mail');
        $mail->setDescription('Your email address');
        $mail->setRequired(true);
        $mail->addValidator('EmailAddress', true);
        $mail->addValidator('EmailConfirmation', false, array('mailRepeat'));

        $mailRepeat = new FKK_Form_Element_Text('mailRepeat');
        $mailRepeat->setLabel('Mail (repeat)');
        $mailRepeat->setDescription('Please confirm your email address');
        $mailRepeat->setRequired(true);
        $mailRepeat->addValidator('EmailAddress', true);
        $mailRepeat->addValidator('EmailConfirmation', false, array('mail'));

        $password = new FKK_Form_Element_Password('password');
        $password->setLabel('Password');
        $password->setDescription('Your password. Must be between 4 and 20 characters.');
        $password->setRequired(true);
        $password->addValidator('StringLength', true, array(4, 20));
        $password->addValidator('PasswordConfirmation', false, array('passwordRepeat'));

        $passwordRepeat = new FKK_Form_Element_Password('passwordRepeat');
        $passwordRepeat->setLabel('Password (repeat)');
        $passwordRepeat->setDescription('Please confirm your password');
        $passwordRepeat->setRequired(true);
        $passwordRepeat->addValidator('StringLength', false, array(4, 20));
        $passwordRepeat->addValidator('PasswordConfirmation', false, array('password'));

        $submit = $this->createElement('submit', 'registerUser');
        $submit->setLabel('Register user');

        $this->addElements(array($mail, $mailRepeat, $password, $passwordRepeat, $submit));
    }
}

The class is just an extension of the Zend_Form class. The only method the class needs to implement is a public init() method which is called from Zend_Form’s constructor.

The init() method above creates some custom text (FKK_Form_Element_Text) and password (FKK_Form_Element_Password) elements. The reason I have made my own elements is so I can do specific stuff with only text and password fields (like adding the Description decorator and a custom plugin prefix. More on this later).

After creating an element I set some properties to it and then add some validators. When adding multiple validators I specify the second argument to the addValidator method ($breakChainOnFailure) to stop the rest of the validation when one of them fails. At least thats what I think $breakChainOnFailure does. :)

The interesting validator here is “EmailConfirmation” and “PasswordConfirmation”. They both to pretty much the same thing so I’ll only describe one of them.

$mail->addValidator('EmailConfirmation', false, array('mailRepeat'));

The code above means that the mail element must have the same value as the “mailRepeat” element. If there are other elements it needs to match as well you can just specify more element names in the array. The third parameter to the addValidator method is passed to the constructor of the validator which will be shown later on. Lets move on!

The custom element classes looks like this:

<?php
require_once 'Zend/Form/Element/Text.php';

class FKK_Form_Element_Text extends Zend_Form_Element_Text {
    public function init() {
        $this->setDisableLoadDefaultDecorators(true);
        $this->addPrefixPath('FKK_Validate', 'FKK/Validate/', 'validate');

        $this->addDecorator('ViewHelper');
        $this->addDecorator('Errors');
        $this->addDecorator('Description', array('escape' => false, 'class' => 'fieldDescription'));
        $this->addDecorator('HtmlTag', array('tag' => 'dd'));
        $this->addDecorator('Label', array('requiredSuffix' => ' *', 'tag' => 'dt', 'class' => 'fieldLabel'));
    }
}

The FKK_Form_Element_Password class is exactly the same except that it extends the Zend_Form_Element_Password class instead so I’ll skip that one.

First I disable the loading of the default decorators and then add a custom prefix path that is used by the plugin loader (Zend_Loader_PluginLoader) that loads up the different decorators and validators. I need to do this so I can magically use my own validators.

Last I add the decorators I want and configure them the way I want them to appear. Most of the stuff is pretty close to the default (with the exception of the Description decorator). As you might notice I only override the public init() method (as I did when extending Zend_Form). The init() method is called from the constructor inherited from Zend_Form_Element_Text and Zend_Form_Element_Password.

And now onto the interesting part … the FKK_Validate_EmailConfirmation validator (as mentioned the PasswordConfirmation validator works exactly the same way so I only cover one of them).

The class looks a little something like this:

<?php
require_once 'Zend/Validate/Abstract.php';

class FKK_Validate_EmailConfirmation extends Zend_Validate_Abstract {
    const NOT_MATCH = 'emailConfirmationNotMatch';

    protected $_messageTemplates = array(
        self::NOT_MATCH => 'Email confirmation does not match'
    );

    /**
     * The fields that the current element needs to match
     *
     * @var array
     */
    protected $_fieldsToMatch = array();

    /**
     * Constructor of this validator
     *
     * The argument to this constructor is the third argument to the elements' addValidator
     * method.
     *
     * @param array|string $fieldsToMatch
     */
    public function __construct($fieldsToMatch = array()) {
        if (is_array($fieldsToMatch)) {
            foreach ($fieldsToMatch as $field) {
                $this->_fieldsToMatch[] = (string) $field;
            }
        } else {
            $this->_fieldsToMatch[] = (string) $fieldsToMatch;
        }
    }

    /**
     * Check if the element using this validator is valid
     *
     * This method will compare the $value of the element to the other elements
     * it needs to match. If they all match, the method returns true.
     *
     * @param $value string
     * @param $context array All other elements from the form
     * @return boolean Returns true if the element is valid
     */
    public function isValid($value, $context = null) {
        $value = (string) $value;
        $this->_setValue($value);

        $error = false;

        foreach ($this->_fieldsToMatch as $fieldName) {
            if (!isset($context[$fieldName]) || $value !== $context[$fieldName]) {
                $error = true;
                $this->_error(self::NOT_MATCH);
                break;
            }
        }

        return !$error;
    }
}

The validator extends the Zend_Validate_Abstract class and contains two methods:

• public function __construct($fieldsToMatch = array())
• public function isValid($value, $context = null)

The constructor is needed so we can store the parameter that is given to the addValidator() method (see above).

The isValid() method simply compares the value of the current element with the values of the other elements it needs to match. The $context parameter is an associative array that contains all the other elements in the form.

The error message follows the same pattern as the other validate classes so we can use Zend_Translate to have different translations of the error message (not covered here).

The only thing left to do now is to display the form and when validating using $form->isValid($_POST); the custom validator will run and display an error next to the fields that is not valid. The following code will do that:

<?php
// Create an instance of the form
$form = new FKK_RegisterUserForm();

// Initialize the array of values that we will populate the form with
$values = array();

// See if anyone has clicked the submit button
if (isset($_POST['registerUser'])) {
    $values = $form->getValues();

    // see if the form is valid
    if ($form->isValid($_POST)) {
        // do some clever stuff here
    }
}

// Populate the form with values
$form->populate($values);

// Display the form
print($form);

And thats about it. :) Please leave comments and if you see any mistakes I made don’t hesitate to tell me about it. :) I am new to Zend_Form so there are probably some stuff that can be done in a different (read: better) way.

---

Possibly related posts: (automatically generated)

• Translating Zend_Form error messages and more
• Q&A
• get values of multiple input elements from a form