ZF Zend Framework

Creating a form object is very simple: simply instantiate Zend_Form:

$form = new Zend_Form;

For advanced use cases, you may want to create a Zend_Form subclass, but for simple forms, you can create a form programmatically using a Zend_Form object.

If you wish to specify the form action and method (always good ideas), you can do so with the setAction() and setMethod() accessors:

$form->setAction('/resource/process')
     ->setMethod('post');

The above code sets the form action to the partial URL "/resource/process" and the form method to HTTP POST. This will be reflected during final rendering.

You can set additional HTML attributes for the <form> tag by using the setAttrib() or setAttribs() methods. For instance, if you wish to set the id, set the "id" attribute:

$form->setAttrib('id', 'login');

A form is nothing without its elements. Zend_Form ships with some default elements that render XHTML via Zend_View helpers. These are as follows:

You have two options for adding elements to a form: you can instantiate concrete elements and pass in these objects, or you can pass in simply the element type and have Zend_Form instantiate an object of the correct type for you.

As some examples:

// Instantiating an element and passing to the form object:
$form->addElement(new Zend_Form_Element_Text('username'));

// Passing a form element type to the form object:
$form->addElement('text', 'username');

By default, these do not have any validators or filters. This means you will need to configure your elements with minimally validators, and potentially filters. You can either do this (a) before you pass the element to the form, (b) via configuration options passed in when creating an element via Zend_Form, or (c) by pulling the element from the form object and configuring it after the fact.

Let's first look at creating validators for a concrete element instance. You can either pass in Zend_Validate_* objects, or the name of a validator to utilize:

$username = new Zend_Form_Element_Text('username');

// Passing a Zend_Validate_* object:
$username->addValidator(new Zend_Validate_Alnum());

// Passing a validator name:
$username->addValidator('alnum');

When using this second option, if the validator can accept constructor arguments, you can pass those in an array as the third parameter:

// Pass a pattern
$username->addValidator('regex', false, array('/^[a-z]/i'));

(The second parameter is used to indicate whether or not failure of this validator should prevent later validators from running; by default, this is false.)

You may also wish to specify an element as required. This can be done using either an accessor or by passing an option when creating the element. In the former case:

// Make this element required:
$username->setRequired(true);

When an element is required, a 'NotEmpty' validator is added to the top of the validator chain, ensuring that the element has a value when required.

Filters are registered in basically the same way as validators. For illustration purposes, let's add a filter to lowercase the final value:

$username->addFilter('StringtoLower');

So, our final element setup might look like this:

$username->addValidator('alnum')
         ->addValidator('regex', false, array('/^[a-z]/'))
         ->setRequired(true)
         ->addFilter('StringToLower');

// or, more compactly:
$username->addValidators(array('alnum',
        array('regex', false, '/^[a-z]/i')
    ))
    ->setRequired(true)
    ->addFilters(array('StringToLower'));

Simple as this is, doing this for every single element in a form can be a bit tedious. Let's try option (b) from above. When we create a new element using Zend_Form::addElement() as a factory, we can optionally pass in configuration options. These can include validators and filters to utilize. So, to do all of the above implicitly, try the following:

$form->addElement('text', 'username', array(
    'validators' => array(
        'alnum',
        array('regex', false, '/^[a-z]/i')
    ),
    'required' => true,
    'filters'  => array('StringToLower'),
));

	Note
	If you find you are setting up elements using the same options in many locations, you may want to consider creating your own Zend_Form_Element subclass and utilizing that class instead; this will save you typing in the long-run.

Rendering a form is simple. Most elements use a Zend_View helper to render themselves, and thus need a view object in order to render. Other than that, you have two options: use the form's render() method, or simply echo it.

// Explicitly calling render(), and passing an optional view object:
echo $form->render($view);

// Assuming a view object has been previously set via setView():
echo $form;

By default, Zend_Form and Zend_Form_Element will attempt to use the view object initialized in the ViewRenderer, which means you won't need to set the view manually when using the Zend Framework MVC. Rendering a form in a view script is then as simple as:

<?php echo $this->form ?>

Under the hood, Zend_Form uses "decorators" to perform rendering. These decorators can replace content, append content, or prepend content, and have full introspection to the element passed to them. As a result, you can combine multiple decorators to achieve custom effects. By default, Zend_Form_Element actually combines four decorators to achieve its output; setup looks something like this:

$element->addDecorators(array(
    'ViewHelper',
    'Errors',
    array('HtmlTag', array('tag' => 'dd')),
    array('Label', array('tag' => 'dt')),
));

(Where <HELPERNAME> is the name of a view helper to use, and varies based on the element.)

The above creates output like the following:

<dt><label for="username" class="required">Username</dt>
<dd>
    <input type="text" name="username" value="123-abc" />
    <ul class="errors">
        <li>'123-abc' has not only alphabetic and digit characters</li>
        <li>'123-abc' does not match against pattern '/^[a-z]/i'</li>
    </ul>
</dd>

(Albeit not with the same formatting.)

You can change the decorators used by an element if you wish to have different output; see the section on decorators for more information.

The form itself simply loops through the elements, and dresses them in an HTML <form>. The action and method you provided when setting up the form are provided to the <form> tag, as are any attributes you set via setAttribs() and family.

Elements are looped either in the order in which they were registered, or, if your element contains an order attribute, that order will be used. You can set an element's order using:

$element->setOrder(10);

Or, when creating an element, by passing it as an option:

$form->addElement('text', 'username', array('order' => 10));

After a form is submitted, you will need to check and see if it passes validations. Each element is checked against the data provided; if a key matching the element name is not present, and the item is marked as required, validations are run with a null value.

Where does the data come from? You can use $_POST or $_GET, or any other data source you might have at hand (web service requests, for instance):

if ($form->isValid($_POST)) {
    // success!
} else {
    // failure!
}

With AJAX requests, you sometimes can get away with validating single element, or groups of elements. isValidPartial() will validate a partial form. Unlike isValid(), however, if a particular key is not present, it will not run validations for that particular element:

if ($form->isValidPartial($_POST)) {
    // elements present all passed validations
} else {
    // one or more elements tested failed validations
}

An additional method, processAjax(), can also be used for validating partial forms. Unlike isValidPartial(), it returns a JSON-formatted string containing error messages on failure.

Assuming your validations have passed, you can now fetch the filtered values:

$values = $form->getValues();

If you need the unfiltered values at any point, use:

$unfiltered = $form->getUnfilteredValues();

So, your form failed validations? In most cases, you can simply render the form again, and errors will be displayed when using the default decorators:

if (!$form->isValid($_POST)) {
    echo $form;

    // or assign to the view object and render a view...
    $this->view->form = $form;
    return $this->render('form');
}

If you want to inspect the errors, you have two methods. getErrors() returns an associative array of element names / codes (where codes is an array of error codes). getMessages() returns an associative array of element names / messages (where messages is an associative array of error code / error message pairs). If a given element does not have any errors, it will not be included in the array.

Let's build a simple login form. It will need elements representing:

For our purposes, let's assume that a valid username should be alphanumeric characters only, start with a letter, have a minimum length of 6, and maximum length of 20; they will be normalized to lowercase. Passwords must be a minimum of 6 characters. We'll simply toss the submit value when done, so it can remain unvalidated.

We'll use the power of Zend_Form's configuration options to build the form:

$form = new Zend_Form();
$form->setAction('/user/login')
     ->setMethod('post');

// Create and configure username element:
$username = $form->createElement('text', 'username');
$username->addValidator('alnum')
         ->addValidator('regex', false, array('/^[a-z]+/'))
         ->addValidator('stringLength', false, array(6, 20))
         ->setRequired(true)
         ->addFilter('StringToLower');

// Create and configure password element:
$password = $form->createElement('password', 'password');
$password->addValidator('StringLength', false, array(6))
         ->setRequired(true);

// Add elements to form:
$form->addElement($username)
     ->addElement($password)
     // use addElement() as a factory to create 'Login' button:
     ->addElement('submit', 'login', array('label' => 'Login'));

Next, we'll create a controller for handling this:

class UserController extends Zend_Controller_Action
{
    public function getForm()
    {
        // create form as above
        return $form;
    }

    public function indexAction()
    {
        // render user/form.phtml
        $this->view->form = $this->getForm();
        $this->render('form');
    }

    public function loginAction()
    {
        if (!$this->getRequest()->isPost()) {
            return $this->_forward('index');
        }
        $form = $this->getForm();
        if (!$form->isValid($_POST)) {
            // Failed validation; redisplay form
            $this->view->form = $form;
            return $this->render('form');
        }

        $values = $form->getValues();
        // now try and authenticate....
    }
}

And a view script for displaying the form:

<h2>Please login:</h2>
<?= $this->form ?>

As you'll note from the controller code, there's more work to do: while the submission may be valid, you may still need to do some authentication using Zend_Auth, for instance.

All Zend_Form classes are configurable using Zend_Config; you can either pass a Zend_Config object to the constructor or pass it in via setConfig(). Let's look at how we might create the above form using an INI file. First, let's follow the recommendations, and place our configurations into sections reflecting the release location, and focus on the 'development' section. Next, we'll setup a section for the given controller ('user'), and a key for the form ('login'):

[development]
; general form metainformation
user.login.action = "/user/login"
user.login.method = "post"

; username element
user.login.elements.username.type = "text"
user.login.elements.username.options.validators.alnum.validator = "alnum"
user.login.elements.username.options.validators.regex.validator = "regex"
user.login.elements.username.options.validators.regex.options.pattern = "/^[a-z]/i"
user.login.elements.username.options.validators.strlen.validator = "StringLength"
user.login.elements.username.options.validators.strlen.options.min = "6"
user.login.elements.username.options.validators.strlen.options.max = "20"
user.login.elements.username.options.required = true
user.login.elements.username.options.filters.lower.filter = "StringToLower"

; password element
user.login.elements.password.type = "password"
user.login.elements.password.options.validators.strlen.validator = "StringLength"
user.login.elements.password.options.validators.strlen.options.min = "6"
user.login.elements.password.options.required = true

; submit element
user.login.elements.submit.type = "submit"

You could then pass this to the form constructor:

$config = new Zend_Config_Ini($configFile, 'development');
$form   = new Zend_Form($config->user->login);

and the entire form will be defined.

Hopefully with this little tutorial, you should now be well on your way to unlocking the power and flexibility of Zend_Form. Read on for more in-depth information!