Forms in general are elements where a lot of parts of an application ‘meet’: Frontend code (HTML/CSS), behavior (JS) and backend processing (validation, filtering and storage). In this post I’ll show how one can:

• Use Zend_Form outside the Zend Framework MVC (most likely an existing project)
• Separate Form rendering from it’s structure
• Use custom validators and decorators

The Form used in this tutorial can be viewed here. The code can be browsed or downloaded on GitHub.

Zend_Form components at a glance

Let’s start with a quick look at how Zend_Form’s different components are tied together:

• A Zend_Form consists of elements, descendants of Zend_Form_Element
• Elements can be supplied with Validators and Filters
• Both the form and it’s elements depend on Decorators to generate HTML. Decorators form a ‘chain’ where each decorator adds HTML to the result of the previous decorators.
• The standard decorators provided by Zend_Form delegate the rendering of the actual HTML to View Helpers

Using Zend_Form without the MVC

As the last point above shows, Zend_Form, through Decorators, makes extensive use of Zend_View helpers. In a Zend_Framework project Zend_Form is able to retrieve the View itself. In other projects (if one wants to use any of Zend_Form’s default decorators) a View instance has to be supplied to Zend_Form:

$view = new Zend_View();
$view->doctype('XHTML1_TRANSITIONAL');
 
$form = new Zend_Form();
$form->setView(new Zend_View());

In this example the doctype is specified in the view. This controls if input elements are rendered with XHTML self-closing tags.

Separate structure and rendering

In this tutorial I create a form for an admin interface where basic user-details can be edited. Let’s assume an ACL implementation dictates that some people can actually edit the details while others are only allowed to view them. I’ve decided to keep the form definition (the ‘model’ side of a form) to a bare minimum and let different renderers (the ‘view’ side) control the output.

For re-usability and keeping controller code clean one can best create form objects by creating an instance of a subclass of Zend_Form:

class My_Form_User extends Zend_Form
{
    public function init() {
        // username
        $this->addElement('text','username', array(
            'required' => true,
            'validators' => array(
                // arguments: type, breakchain, validator constructor options
                array('Alnum', false, false),
                array('StringLength', false, array(6, 16)),
            ),
        ));
 
        // email
        $EmailValidate = new My_Validator_Email();
        $this->addElement('text','email', array(
            'required' => true,
            'validators' => array(
                array('EmailAddress', false),
                array($EmailValidate, false)
            )
        ));
 
        // ...
    }
}

(As can be seen I create an instance of My_Validate_Email and add that to the email element. We’ll look into that later. First, let’s continue with the form definition.)

The init() method is designed for this type of form definition, thereby avoiding the need to duplicate the constructor and it’s parameter scheme. As can be seen, I only define the form elements and validators. Labels and such I defer to the renderer (more on that later). As this is about integrating Zend_Form into existing projects that are not based on Zend Framework, I assume there is some sort of language-aware component. In this example I use a language pack that returns language-specific results based on tags. Adding a set of checkboxes then looks like this:

class My_Form_User extends Zend_Form
{
    public function init() {
 
        // ...
 
        $lang = new My_LanguagePack();
 
        $groupIds = array(1,2,3,4);
        $groupOptions = array();
        foreach ($groupIds as $id) {
            $groupOptions[$id] = $lang->get('group.label.' . $id);
        }
 
        $elmGroup = new Zend_Form_Element_MultiCheckbox('group');
        $elmGroup->setMultiOptions( $groupOptions );
        $elmGroup->setRequired(true);
        $this->addElement($elmGroup);
    }
}

Now I create two renderer classes for both the ‘edit’ and ‘view’ display mode. Both accepting a Zend_Form instance in the constructor. Code below shows how the form is displayed using either rendering class:

$Form = new My_Form_User();
 
$RendererEdit = new My_Form_Renderer_Edit($Form, 'user_edit');
echo $RendererEdit->render();
 
$RendererView = new My_Form_Renderer_View($Form, 'user_view');
echo $RendererView->render();

But before moving onto the renderers, let’s look into the aforementioned My_Email_Validator class.

Adding a custom validator

When specifying validators by string, as is done with ‘EmailAddress’, Zend_Form adds one of the types of Zend_Validate. For validation not covered by the standard validators one can create a custom validator by extending Zend_Validate_Abstract or implementing Zend_Validator_Interface. For email addresses, a typical scenario would be a custom validator that connects to a database and checks if the given email address is allready used by another user. For this demo I skip the database part, resulting in:

class My_Validator_Email extends Zend_Validate_Abstract
{
    protected $isValid = null;
 
    public function isValid($value) {
        $this->isValid = !in_array($value, array(
            'duplicate@test.com',
        ));
        return $this->isValid;
    }
 
    public function getMessages() {
        if ($this->isValid === false) {
            return array(
                'duplicateEmail' => 'This email address is allready used'
            );
        }
        return array();
    }
 
    public function getErrors() {
        return array_keys($this->getMessages());
    }
}

Now let’s continue with the two renderer classes:

Rendering the edit mode

The basics of the My_Form_Renderer_Edit class constructor are shown below:

class My_Form_Renderer_Edit
{
    protected $form;
 
    protected $lang;
 
    public function __construct(Zend_Form $form, $form_id = null)
    {
        $view = new Zend_View();
        $view->doctype('XHTML1_TRANSITIONAL');
 
        $this->form = $form;
        $this->form->setView(new Zend_View());
        $this->form->setAttrib('class', 'form_edit');
        if (!is_null($form_id)) {
            $this->form->setAttrib('id', $form_id);
        }
 
        $this->lang = new My_LanguagePack();
    }
 
    public function render()
    {
        // ...
}

As can be seen this is where I setup the view (as mentioned before) and set id and classname that can be used in CSS. I want the HTML to look like this:

<ul>
    <li class="">
        <div id="username-label"><label for="username" class="required">* Username</label></div>
        <div class="element">
            <input type="text" name="username" id="username" value="" class="text" />
            <span class="description">(Min 6, max 16 char.)</span>
        </div>
    </li>
</ul>

When the render() method is called on the renderer class I do four things:

• Add a submit element
• Setup element properties that are common for all elements
• Setup properties on a per-element basis
• Setup properties of the form element

I’ll briefly run through those steps. Complete code for My_Form_Renderer_Edit can be seen on Github.

Add a submit element

As long as the submit value doesn’t play a role in the processing of entered data I consider this part of the view layer. For example, interaction design might dictate that on long forms submit buttons are placed both above and below the form.

Setup common properties

By using the method setElementDecorators() of Zend_Form, all default decorators are replaced by the ones specified. The decorators that fit my needs are ViewHelper (renders the element itself) and Description, resulting in:

    protected function setupElementsCommon()
    {
         $this->form->setElementDecorators(array(
            'ViewHelper',
            array('Description', array(
                'placement' => 'append',
                'tag' => 'span',
                'class' => 'description'
            )),
         ));
    }

Setup per-element properties

Here I add additional decorators. First I setup the element’s label and description properties by using the language pack, then I add the appropriate decorators. Furthermore I add some additional classnames to elements. If the element has an error I not only want to display the errors (using a custom decorator, more on that later). I also want to give the HTML element wrapped around all of the parts an ‘error’ classname.

        $elmHasError = (count($elm->getMessages()) > 0);
        $liClass = $elmHasError ? 'error' : '';
        $elm->addDecorator(
            array('outerLi' => 'HtmlTag'),
            array('tag' => 'li', 'class' => $liClass)
        );

Setup the form object

Finally the Form is configured. After removing all existing decorators, three decorators are added. The only difference with the default set of decorators is the UL element used in the HtmlTag decorator:

    protected function setupForm()
    {
        $this->form->clearDecorators();
        $this->form->addDecorator('FormElements');
        $this->form->addDecorator('HtmlTag', array('tag' => 'ul'));
        $this->form->addDecorator('Form');
    }

Adding a custom decorator

The complete code shows that instead of the default ‘Errors’ decorator I provide my own. This way I can retrieve the error messages provided by the form element and then replace them with messages retrieved from the languagePack. A custom decorator needs to extend Zend_Form_Decorator_Abstract or implement Zend_Form_Decorator_Interface. Excerpts from My_Decorator_Errors:

    public function render($content)
        $element = $this->getElement();
        $errorMessages = $element->getMessages();
        if (empty($errorMessages)) {
            return $content;
        }
 
        // iterate over errorMessages, replace or use default
        $errorLinesHtml = '';
        foreach ($errorMessages as $errorCode => $errorMsg) {
            // make an exception for isEmpty and array representing elements
            if ($element->isArray() && $errorCode=='isEmpty') {
                $msgLangPack = $this->lang->get('form.error.array.' . $errorCode);
            } else {
                $msgLangPack = $this->lang->get('form.error.' . $errorCode);
            }
            $errorMsg = ($msgLangPack !== false) ? $msgLangPack : $errorMsg;
            $errorLinesHtml .= '<li>' . $errorMsg . '</li>';
        }
        // combine
        $errorHtml = '<ul class="errors">' . $errorLinesHtml .'</ul>';
 
        // ...

Errormessages are fetched by an element’s getMessages() method that returns an associative array. The error-codes (keys) can be used to translate the message. As can be seen I treat elements representing an array differently when fetching the ‘isEmpty’ error message.

Rendering the view mode

The view renderer is a simplified version of the edit renderer. Main differences are:

• The form doesn’t have a Form decorator and thereby no form tag. (I’ll keep calling the no-form a form though ;)).
• All elements have only one decorator common for all elements: My_Decorator_View_Element
• As the only element decorator doesn’t use Zend_View, the form has no need for a View element.

My_Decorator_View_Element

This decorator retrieves value and label from the element and creates. It then creates HTML making exceptions for:

• Submit elements (which are ignored)
• Array representing elements (where more than one value needs to be displayed)

Concluding

Above examples give an impression of how Zend_Form can be suited to virtually anyone’s needs. One can argue that separating the rendering from the basic definition adds unnecessary complexity. It does however pull HTML specifics (which during a project life-cycle often are subject to change) out of the ‘model’ layer. Both the stripped down forms and renderers are easy to reuse: The renderer can be applied to a number of forms and the forms themselves can be used in projects requiring different HTML.

Even without considering the rendering part, Zend_Form is a valuable platform offering a lot of ways to customize it. As the view renderer example shows it can also operate without Zend_View, provided one doesn’t use any of the built in decorators. Being able to provide self-built elements, validators and decorators makes it possible to use Zend_Form in virtually any project.

Further reading:

• Zend Framework API documentation
• Decorators with Zend_Form
• Rendering Zend Form decorators individually
• Advanced Zend_Form usage

Two talks were scheduled and Stefan Koopmanschap kicked off the meeting with a presentation titled “Integrating Symfony and Zend Framework” (slides). After a short introduction pointing out the benefits of using any framework at all, Stefan showed how both Symfony’s and Zend Framework’s autoloaders can be initialized in the application’s bootstrap code. After that using ZF components in symfony was showcased by using Zend_Service_Twitter inside a Symfony project. Being quite familiar with Zend Framework that was not really surprising (to me) but the part following was: Integrating Symfony into a Zend Framework project. First of all it was new to me that there are “Symfony Components“. Apparently Symfony is not an all-or-nothing affair anymore. Most of the components were briefly covered of which I especially found the Event Dispatcher highly interesting.

After a brief pause, Juliette Reinders Folmer hosted the big “Why Equal Doesn’t Equal Quiz”. 65 Questings testing the knowledge of the attendees about the type conversions going on when writing code like:

$a = null;
if (empty($a)) echo 'empty';
 
foreach(array('test','0','etc...') as $val) {
    if ($val) echo 'has value';
}

Questions like the ones above where the easy ones… Especially interesting where the ctype family of functions. They are especially usefull for checking database result or GPC data. Although I had seen the ctype functions before I kind of forgot about them so especially there I had wrong answers. Score: 45 out of 65.

The evening concluded with some informal chatting and some beers generously provided by Freshheads. As usual I went home with some new things on my ‘got to check that out’ list…

public function testLogoutShouldDenyAccess()
{
    $this->login();
 
         // verify that profile page now doesn't contain login form
    $this->dispatch('/profile');
    $this->assertQueryCount('form#login', 0);
 
        // dispatch logout page
    $this->dispatch('/login/logout');
 
        // verify that profile now holds login form
    $this->dispatch('/profile');
    $this->assertQueryCount('form#login', 1);
    $this->assertNotController('profile');
}

This failed on the last assertQueryCount() which left me puzzled. Performing above steps manually seemed to work fine so I was overlooking something either in my app-code or the test-code.

Adding a var_dump at the end of the test method gave some insight.

var_dump($this->getResponse());

Showed a response object with a protected variable _body containing (simplified for clarity):

<html>
<head>
<title></title>
</head>
<body>
<h1>login</h1>
    <html>
    <head>
    <title></title>
    </head>
    <body>
    <h1>logout</h1>
    </body>
    </html>
<form id="login" action="" method="post">
<!-- form contents -->
</form>
</body>
</html>

Apparantly the total content of a previous request is prepended to the view part of the next request, resulting in incorrect html the assertQuery() method can’t handle. Looking into the login() helper method I made earlier:

public function login()
{
        //login
    $this->request->setMethod('POST')
         ->setPost(array(
              'un' => 'testun',
              'pw' => 'testpw'
         ));
    $this->dispatch('/login/login');
    $this->assertRedirectTo('/');
        // reset
    $this->resetRequest()
         ->resetResponse();
        // reset post
    $this->request->setPost(array());
}

Apparently I forgot to reset the response object as adding that to the test method solved the issue. So for testing multiple requests in one test method one needs to reset the response to prevent incorrect html. This can be simplified by using below custom dispatch method that also allows setting POST data:

public function doDispatch($url,$post=null)
{
        // reset everything
    $this->resetRequest()
         ->resetResponse();
    $this->request->setPost(array());
 
        // add post-data if given
    if (is_array($post)) {
        $this->request->setMethod('POST');
        $this->request->setPost(array(
            'un' => 'testun',
            'pw' => 'testpw'
        ));
    }
 
        // dispatch
    $this->dispatch($url);
}

Loading configuration data

Basically there are three ways of loading configuration data:

• 1.Using Zend_Config and passing a PHP array as parameter
• 2.Using Zend_Config_Ini to load an ini configuration file
• 3.Using Zend_Config_Xml to load an xml configuration file

$configData = array(
  'somecategory'  => array(
    'somesetting'     => 'somevalue',
  )
);
  // 1. Load array
$config = new Zend_Config($configData);
  // 2. Load ini file
$config = new Zend_Config_Ini('/path/to/config.ini');
  // 3. Load xml file
$config = new Zend_Config_Xml('/path/to/config.xml');

Alternatively, you can specify a file containing an array as require() returns the return value of a PHP script being included:

config.php

<?php
$CONFIG['somecategory']['somesetting'] = 'somevalue';
 
return $CONFIG;

  // 1b Load array
$config = new Zend_Config(require 'path/to/config.php');

Using configuration data

Zend_Config creates a hierachy of Zend_Config instances. So a specific part of the total configuration data can be extracted and passed to a specific component. All subparts behave the same. If the component requires configuration to be passed as an array the toArray() method can be used. Instead of accessing values as properties one can also use the get() method. The advantage of get() is that a default value can be supplied to be used when the requested variable isn’t available.

  // configure an instance using a specific part of the config
$modelComponent = new ModelComponent($config->components->componentName);
  // Or, if the component requires an array
$modelComponent = new ModelComponent($config->components->componentName->toArray());
  // Get an optional config setting, supplying a default value
$someValue = $config->common->get('someValue','myDefaultValue');

The data contained in Zend_Config is read-only which is normally a good thing. In case the configuration data has to be changed this can be overridden by supplying an additional parameter in the constructor. Then after making the neccessary changes the config object can be ’sealed’ by calling setReadOnly().

  // read config with $allowModifications set to true
$config = new Zend_Config(require 'path/to/config.php',true);
 
  // perhaps change some bits here and there
if ($fullMoonMadness)
{
  $config->site->theme = 'silver';
  $config->blog->allowComments = false;
}
 
  // and prevent accidental modification
$config->setReadOnly();

To make the loaded configuration available throughout the entire application, Zend_Registry is probably the tool of choice.

$config = new Zend_Config(require 'path/to/config.php');
  // and store in registry
Zend_Registry::getInstance()->set('config', $config);

Organizing configuration data

When using ini or xml configuration files, sections can be declared. On loading the file the section to be used can be specified. A section can extend other sections thereby allowing configuration data to have a certain hierarchy.

Ini-file example:

[production]
www_root = www.mysite.com
site.title = "My Website - "
 
[test : production]
www_root = test.mysite.com

The root node of XML files can be named arbitrarily. If you want to use sections the first level in the XML has to correspond to the section requested. There are two reserved attributes: value and extends. Other attributes can hold values that otherwise would be childnodes. See example that holds the same data as the Ini file above:

<?xml version="1.0"?>
<config>
  <production>
	<www_root>www.mysite.com</www_root>
    <site title="My Website - " />
  </production>
  <test extends="production">
   <www_root value="test.mysite.com" />
 </test>
</config>

Now the section-specific configuration can be loaded by specifying a second parameter in the constructor:

$config = new Zend_Config_Xml('/path/to/config.xml','test');

Ini, XML or Array?

As mentioned at the top of this article: There is no ‘only’ way and there is no ‘right’ or ‘wrong’ way. Of course there are aspects that can make you favor one approach over the other, the most notable being:

• Only Ini and XML provide sections, allowing you to use hierarchic configuration data
• Ini and especially XML are better suited for tooling: Software other than PHP can read or modify configuration data.
• When using ini files it is not possible to use quotes in a value.
• PHP arrays have the benefit that you can put program logic in them. For example, you can construct variables based on defaults that are set initially. See example below

$CONFIG['defaults']['fs_root'] = '/var/www/mysite_com/';
// ...
$CONFIG['locations']['libraries']['zf'] = $CONFIG['defaults']['fs_root'].'lib/zf/';
 
return $CONFIG;

2009-05-15: added example of loading specific section by passing section parameter to constructor