The Zend Framework in Practice » Zend_Validate

The Login Page: The Login Form

James — Mon, 15 Nov 2010 22:51:07 +0000

The Login Form is a simple form, consisting of three elements: the username field, the password field and the login button.

The form class is derived from an abstract base class of my devising. This contains the functionality shared between all forms in an application. The abstract base class is itself derived from Zend_Form.

The abstract base class is defined as follows:

abstract class Application_Form_Abstract extends Zend_Form
{
  public function getFieldDecorators()
  {
    return array('ViewHelper', 
      array('HtmlTag', array('tag' => 'dd')), 
      array('Label', array('tag'  => 'dt'))
    );
  }
 
  public function getFirstFormError()
  {
    $fields = $this->getMessages();
 
    foreach ($fields as $field => $messages)
    {
      foreach ($messages as $message)
      {
        $error = array('message' => $message, 'field' => $field);
        return $error;
      }
    }
 
    return null;
  }
}

The class supplies contains two functions, both of which are connected to the rendering of error messages.

The first function modifies the standard field decorators to remove the error decorator, as I don’t usually want any error messages displayed beside the field. Instead, I prefer to show the first error message at the top of the form; it is the task of the second function to retrieve this.

The actual Login form class is straighforward:

class Application_Form_Login extends CapArgo_Form_Abstract
{
  public function init()
  {
    $this->setAttrib('id', 'login_form');
 
    $this->setMethod('post');
 
    $this->addElement(
      'text', 'username', array(
        'label'      => 'Username:',
        'maxLength'    => 64,
        'required'    => true,
        'filters'    => array('StringTrim'),
        'decorators'  => $this->getFieldDecorators(),
        'errorMessages'  => array('Please enter your username')
      )
    );
 
    $this->addElement(
      'password', 'password', array(
        'label'      => 'Password:',
        'maxLength'    => 64,
        'required'    => true,
        'decorators'  => $this->getFieldDecorators(),
        'errorMessages'  => array('Please enter your password')
      )
    );
 
    $this->addElement(
      'submit', 'submit', array(
        'ignore'    => true,
        'label'      => 'Login'
      )
    );
  }
}

The above code needs little explanation.

Note that there is a call to $this->getFieldDecorators() in order to attach the proper decorators to the input fields.

Also, note that the required option is set to true, and an error message is supplied, should the user fail to enter either a username or password; this uses Zend_Validate_NotEmpty to check that the user has entered a value.

Checking that a password is repeated correctly using Zend_Validate_Identical

James — Sun, 01 Aug 2010 09:41:44 +0000

When a user is asked to enter a new password, it is customary to ask the user to repeat it, in order to reduce the risk of it being entered incorrectly. In the Zend Framework, there is a validator that can check whether two items are identical, but using it with Zend_Form is tricky, because it needs the values of two fields to make the comparison, while validators are attached to a single field, independently of the others. This article looks at how to use Zend_Validate_Identical with Zend_Form.

Let us assume that we are adding our password and password repeat fields in the init method of our form class, which is derived from Zend_Form:

    $this->addElement(
      'password', 'password', array(
        'label'      => 'Password:',
        'maxLength'    => 64,
        'required'    => true,
        'decorators'  => $this->getFieldDecorators(),
        'errorMessages'  => array('Please enter a password')
      )
    );
 
    $this->addElement(
      'password', 'repeat_password', array(
        'label'      => 'Repeat Password:',
        'maxLength'    => 64,
        'required'    => true,
        'decorators'  => $this->getFieldDecorators(),
        'errorMessages'  => array('Please repeat the password correctly')
      )
    );

Note that both fields have the required option set to true; this is necessary event in the case of the repeat_password field, where we will be adding another validator later on. Also note that we have specified custom error messages for both fields, since the default messages are not appropriate.

The second and final step is to override the isValid method of the form class, and add the validator there:

  public function isValid($data)
  {
    $this->getElement('repeat_password')->
      addValidator(new Zend_Validate_Identical($data['password']));
 
    return parent::isValid($data);
  }

It is necessary to do it at this point, since it is only then that we have access to the value of the password field.

The form will now fail to validate if the password is not repeated correctly, and the appropriate error message will be generated.

The Contact Page: The Contact Form

James — Sat, 07 Nov 2009 16:49:45 +0000

Although the example website currently only has one form, the contact form, other forms may be added to it in the future; therefore, in implementing the form, I created an abstract base class for site forms, which contains the functionality shared by all forms.

The abstract class is called Default_Form_Abstract and is stored in the application/forms directory. It is derived from Zend Form.

The skeleton abstract class declaration is as follows:


abstract class Default_Form_Abstract extends Zend_Form
{
  // The class methods and variables are declared here.
}

The Zend_Form module uses the decorator pattern to define the markup used to render a form. The base form class uses decorators to render the forms as tables. The decorators used to render the form fields are contained in the following two variables:

  private $_fieldDecorators = array(
    'ViewHelper',
    array(array('data' => 'HtmlTag'), 
array('tag' => 'td', 'class' => 'element')),
    array('Label', array('tag' => 'td')),
    array(array('row' => 'HtmlTag'), 
array('tag' => 'tr'))
  );
 
  private $_buttonDecorators = array(
    'ViewHelper',
    array(array('data' => 'HtmlTag'), 
array('tag' => 'td', 'class' => 'element')),
    array(array('label' => 'HtmlTag'), 
array('tag' => 'td', 'placement' => 'prepend')),
    array(array('row' => 'HtmlTag'), 
array('tag' => 'tr'))
  );

These decorators are applied to field elements declared in derived classes using the following two methods. The first is used for most fields, which have labels; the second is used for buttons such as the submit button, which don’t have a label:

  public function setFieldDecorators($field)
  {
    $field->setDecorators($this->_fieldDecorators);
  }
 
  public function setButtonDecorators($button)
  {
    $button->setDecorators($this->_buttonDecorators);
  }

The overall styling for the form is set in the init method:

  public function init()
  {
    // Set the form decorators
    $this->setDecorators(
      array(
        'FormElements',
        array('HtmlTag', array('tag' => 'table')),
        'Form'
      )
    );
  }

Finally, there is a method used to retrieve the first error message generated by a failed validation:

  public function getFirstFormError()
  {
    $fields = $this->getMessages();
 
    foreach ($fields as $field => $messages)
    {
      foreach ($messages as $message)
      {
        $error = array('message' => $message, 'field' => $field);
        return $error;
      }
    }
 
    return null;
  }

This method is necessary as normally details of all fields that have failed validation are returned, but the usual (and my preferred) practice is to only report the first field that has failed validation. This has always struck me as less confusing for the user.

The abstract class is called Default_Form_Abstract and is stored in the application/forms directory. It is derived from Zend Form.

The skeleton abstract class declaration is as follows:


class Default_Form_Contact extends Default_Form_Abstract
{
  public function init()
  {
    // The code used to initialise the form is inserted here.
  }
}

The init method starts by calling the init method of the parent class:

    parent::init();

This is essential as the parent method sets up the form decorators.

Next the method sets the form ID:

    // Set the form ID
    $this->setAttrib('id', 'contact_form');

Then the method sets the form submission method to POST:

    // Submit the form using a POST request
    $this->setMethod('post');

The first form element is the Name field, which is a normal text field.

The script first creates an appropriate form element:

    // Name field
    $name = new Zend_Form_Element_Text('name',
      array(
        'label'      => 'Your name:', 
        'required'    => true, 
        'filters'    => array('StringTrim'),
        'maxlength'    => 64
      )
    );

The first parameter is the field name/id.

The second parameter is an array of additional settings. Here these are:

label: This specifies the label attached to the field.
required: This specifies whether the field is required; in this case it is, so the field will fail validation if it is not.
filters: This specifies the filters to apply to the field; in this case, it is the trim filter, used to remove leading and trailing space.
maxlength: This specifies the maximum length of the data than can be entered in the field.

The script then adds the error message to display, if the field fails validation:

    $name->setErrorMessages(array('Please enter your name.'));

The script then adds the appropriate decorators to the field, to ensure that it is rendered as a table row:

    $this->setFieldDecorators($name);

Finally the field is added to the form:

    $this->addElement($name);

A similar process is followed for the other form fields:

    // E-mail field
    $email = new Zend_Form_Element_Text('email', 
      array(
        'label'      => 'Your e-mail address:', 
        'required'    => true, 
        'filters'    => array('StringTrim'), 
        'validators'  => array('EmailAddress'),
        'maxlength'    => 255
      )
    );
    $email->setErrorMessages(
array('Please enter a valid e-mail address.'));
    $this->setFieldDecorators($email);
    $this->addElement($email);
 
    // Message field
    $message = new Zend_Form_Element_Textarea('message', 
      array(
        'label'     => 'Your message:',
        'required'  => true,
        'rows'      => 6,
        'cols'      => 50
      )
    );
    $message->setErrorMessages(array('Please enter a message.'));
    $this->setFieldDecorators($message);
    $this->addElement($message);
 
    // Submit button
    $submit = new Zend_Form_Element_Submit('submit', 
      array(
        'ignore'    => true, 
        'label'     => 'Send',
        'class'     => 'ui-state-default ui-corner-all'
      )
    );
    $this->setButtonDecorators($submit);
    $this->addElement($submit);

The e-mail field has a specific validator applied to it, rather than the general required setting.

The text area has its rows and columns set, rather than a maxlength.

Note that the submit button has different decorators applied to it, as unlike the other fields, it does not have a label.

In my next most, I shall finish my coverage of the contact page by looking at the class used to send the contact e-mail.