Jun 14 / Richard Knop

Extending Zend_Form

Zend_Form is one of the key Zend Framework components. It greatly simplifies handling of HTML forms and can cooperate with other Zend Framework components such as Zend_Filter, Zend_Validate or Zend_View.

There are other ways to use it but I usually extend the Zend_Form class and create a separate class for each form in my application. Moreover, I almost exclusively use the MVC design pattern and therefor I use Zend_Form together with Zend_View.

Build a form

Here’s an example of a simple contact form:

  1. class Contact extends Zend_Form
  2. {
  3.     public function init()
  4.     {
  5.         $this->setMethod('post');
  6.  
  7.         $name = new Zend_Form_Element_Text('name', array(
  8.             'label' => 'Your name',
  9.             'required' => true,
  10.             'filters' => array(
  11.                 'StringTrim'
  12.             ),
  13.             'validators' => array(
  14.                 array('StringLength', false, array(3, 50))
  15.             ),
  16.             'class' => 'input-text'
  17.         ));
  18.  
  19.         $email = new Zend_Form_Element_Text('email', array(
  20.             'label' => 'Your email',
  21.             'required' => true,
  22.             'filters' => array(
  23.                 'StringTrim'
  24.             ),
  25.             'validators' => array(
  26.                 'EmailAddress'
  27.             ),
  28.             'class' => 'input-text'
  29.         ));
  30.  
  31.         $subject = new Zend_Form_Element_Text('subject', array(
  32.             'label' => 'Subject',
  33.             'required' => true,
  34.             'filters' => array(
  35.                 'StringTrim'
  36.             ),
  37.             'validators' => array(
  38.                 array('StringLength', false, array(3, 50))
  39.             ),
  40.             'class' => 'input-text'
  41.         ));
  42.  
  43.         $message = new Zend_Form_Element_Textarea('message', array(
  44.             'label' => 'Message',
  45.             'rows' => 10,
  46.             'cols' => 50,
  47.             'required' => true,
  48.             'filters' => array(
  49.                 'StringTrim'
  50.             ),
  51.             'validators' => array(
  52.                 array('StringLength', false, array(20, 1500))
  53.             )
  54.         ));
  55.  
  56.         $captcha = new Zend_Form_Element_Captcha('captcha', array(
  57.             'label' => 'Are you a human?',
  58.             'helper' => null,
  59.             'captcha' => array(
  60.                 'captcha' => 'Figlet',
  61.                 'wordLen' => 6,
  62.             ),
  63.             'class' => 'input-text'
  64.         ));
  65.  
  66.         $submit = new Zend_Form_Element_Submit('contact', array(
  67.             'label' => 'Submit',
  68.             'class' => 'input-submit'
  69.         ));
  70.  
  71.         $this->addElements(array($name, $email, $subject, $message, $captcha, $submit));
  72.     }
  73. }

The first thing I did was to set a HTTP method to POST with setMethod(). Other option is to use HTTP GET. Next I created an object for every form element. As you can see, there are three input text fields (name, email, subject), one textarea (message), a captcha and a submit button.

Zend Framework contains classes for all HTML form elements you could ever need plus also a wide range of captcha classes. Every element object constructor takes two arguments: the first is an HTML name attribute, the second is array of other HTML attributes such as label or class and additional attributes such as filters and validators.

What’s the difference between filters and validators?

  • A filter normalizes input values to match an expected format. A typical example is the StringTrim filter which removes whitespace from the beginning and end of a string. Filters are executed before validation takes place.
  • A validator tests input values against some criteria. Values are not changed and the validator reports back whether the input values passed the test or not. A typical example would be the EmailAddress validator which checks if an input value is a valid email address.

The last line of the class – addElements() – adds elements to the form. You can you use the addElement() method to add a single element, too.

Validate the form

First, you need to create an instance of the form class. I use a simple method to do that for me:

  1. private function _getForm($form, $action)
  2. {
  3.     include APPLICATION_PATH . '/modules/' . $this->_request_>getModuleName()
  4.     . '/forms/' . $form . '.php';
  5.     $form = new $form();
  6.     $form->setAction($action);
  7.     return $form;
  8. }

Second, in a controller action you load the form and validate it:

  1. public function contactAction()
  2. {
  3.     // get the request object
  4.     $request = $this->getRequest();
  5.  
  6.     // load the Contact form
  7.     $form = $this->_getForm('Contact',
  8.                             $request->getActionName());
  9.     // if POST data has been submitted
  10.     if ($request->isPost()) {
  11.         // if the Contact form has been submitted and the submitted data is valid
  12.         if (isset($_POST['contact']) && $form->isValid($_POST)) {
  13.  
  14.             // get the form values
  15.             $data = $form->getValues();
  16.  
  17.             /*
  18.              * do something here
  19.              * for example, send an email using Zend_Mail
  20.              */
  21.  
  22.             /*
  23.              * reset the form fields
  24.              * in case a user resubmits the form
  25.              * (by hitting F5 for instance)
  26.              */
  27.              $form->reset();
  28.  
  29.         }
  30.     }
  31.  
  32.     // pass the form to the view so it can be rendered
  33.     $this->view->form = $form;
  34. }

Render the form

We have already passed the form to the view, so we can render it:

  1. <h2>Contact form</h2>
  2. <?php echo $this->form, "\n"; ?>

And how does it look like? Here is the result with almost no styling:

Contact form

After you submit the form Zend_Form will take care of filtering and validating the input values and it will also render errors:

Contact form submitted

The default XHTML markup uses a definition list for form elements. Form elements are rendered like this:

<dt><label for="foo">Foo</label><dt>
<dd>
<input name="foo" id="foo" type="text" value="" />
<div><ul>
<li>...</li>
</ul></div>
</dd>

That’s not a bad markup but it might not fit everybody’s needs (I use an ordered list instead of a definition list). Fortunately, you can customize the markup easily using decorators. Decorators? What’s that?

Well, Zend_Form uses the Decorator design pattern to build the XHTML markup. Decorators in Zend Framework are a little bit more advanced topic but they are still pretty easy to work with. I recommend reading this article to understand how they work.

Filed under PHP, Zend Framework
Leave a Comment