PHP5

Zend_Form_Element makes use of Zend_Loader_PluginLoader to allow developers to specify locations of alternate validators, filters, and decorators. Each has its own plugin loader associated with it, and general accessors are used to retrieve and modify each.

The following loader types are used with the various plugin loader methods: 'validate', 'filter', and 'decorator'. The type names are case insensitive.

The methods used to interact with plugin loaders are as follows:

Custom validators, filters, and decorators are an easy way to share functionality between forms and encapsulate custom functionality.

<?php class My_Decorator_Label extends Zend_Form_Decorator_Abstract
{
    protected $_placement = 'PREPEND';

    public function render($content)
    {
        if (null === ($element = $this->getElement())) {
            return $content;
        }
        if (!method_exists($element, 'getLabel')) {
            return $content;
        }

        $label = $element->getLabel() . ':';

        if (null === ($view = $element->getView())) {
            return $this->renderLabel($content, $label);
        }

        $label = $view->formLabel($element->getName(), $label);

        return $this->renderLabel($content, $label);
    }

    public function renderLabel($content, $label)
    {
        $placement = $this->getPlacement();
        $separator = $this->getSeparator();

        switch ($placement) {
            case 'APPEND':
                return $content . $separator . $label;
            case 'PREPEND':
            default:
                return $label . $separator . $content;
        }
    }
}

$element->addPrefixPath('My_Decorator', 'My/Decorator/', 'decorator');

$form->addElementPrefixPath('My_Decorator', 'My/Decorator/', 'decorator');

It's often useful and/or necessary to perform some normalization on input prior to validation -- for instance, you may want to strip out all HTML, but run your validations on what remains to ensure the submission is valid. Or you may want to trim empty space surrounding input so that a StringLength validator will not return a false positive. These operations may be performed using Zend_Filter, and Zend_Form_Element has support for filter chains, allowing you to specify multiple, sequential filters to utilize. Filtering happens both during validation and when you retrieve the element value via getValue():

<?php
$filtered = $element->getValue();
?>

Filters may be added to the chain in two ways:

Let's see some examples:

<?php
// Concrete filter instance:
$element->addFilter(new Zend_Filter_Alnum());

// Fully qualified class name:
$element->addFilter('Zend_Filter_Alnum');

// Short filter name:
$element->addFilter('Alnum');
$element->addFilter('alnum');
?>

Short names are typically the filter name minus the prefix. In the default case, this will mean minus the 'Zend_Filter_' prefix. Additionally, the first letter need not be upper-cased.

	Using Custom Filter Classes
	If you have your own set of filter classes, you can tell Zend_Form_Element about these using addPrefixPath(). For instance, if you have validators under the 'My_Filter' prefix, you can tell Zend_Form_Element about this as follows: <?php $element->addPrefixPath('My_Filter', 'My/Filter/', 'filter'); ?> (Recall that the third argument indicates which plugin loader on which to perform the action.)

If at any time you need the unfiltered value, use the getUnfilteredValue() method:

<?php
$unfiltered = $element->getUnfilteredValue();
?>

For more information on filters, see the Zend_Filter documentation.

Methods associated with filters include:

If you subscribe to the security mantra of "filter input, escape output," you'll want to validate ("filter input") your form input. In Zend_Form, each element includes its own validator chain, consisting of Zend_Validate_* validators.

Validators may be added to the chain in two ways:

Let's see some examples:

<?php
// Concrete validator instance:
$element->addValidator(new Zend_Validate_Alnum());

// Fully qualified class name:
$element->addValidator('Zend_Validate_Alnum');

// Short validator name:
$element->addValidator('Alnum');
$element->addValidator('alnum');
?>

Short names are typically the validator name minus the prefix. In the default case, this will mean minus the 'Zend_Validate_' prefix. Additionally, the first letter need not be upper-cased.

Using Custom Validator Classes

If you have your own set of validator classes, you can tell Zend_Form_Element about these using addPrefixPath(). For instance, if you have validators under the 'My_Validator' prefix, you can tell Zend_Form_Element about this as follows: <?php $element->addPrefixPath('My_Validator', 'My/Validator/', 'validate'); ?> (Recall that the third argument indicates which plugin loader on which to perform the action.)

If failing a particular validation should prevent later validators from firing, pass boolean true as the second parameter:

<?php
$element->addValidator('alnum', true);
?>

If you are using a string name to add a validator, and the validator class accepts arguments to the constructor, you may pass these to the third parameter of addValidator() as an array:

<?php
$element->addValidator('StringLength', false, array(6, 20));
?>

Arguments passed in this way should be in the order in which they are defined in the constructor. The above example will instantiate the Zend_Validate_StringLenth class with its $min and $max parameters:

<?php
$validator = new Zend_Validate_StringLength(6, 20);
?>

Providing Custom Validator Error Messages

Some developers may wish to provide custom error messages for a validator. Zend_Form_Element::addValidator()'s $options argument allows you to do so by providing the key 'messages' and setting it to an array of key/value pairs for setting the message templates. You will need to know the error codes of the various validation error types for the particular validator. A better option is to use a Zend_Translate_Adapter with your form. Error codes are automatically passed to the adapter by the default Errors decorator; you can then specify your own error message strings by setting up translations for the various error codes of your validators.

You can also set many validators at once, using addValidators(). The basic usage is to pass an array of arrays, with each array containing 1 to 3 values, matching the constructor of addValidator():

<?php
$element->addValidators(array(
    array('NotEmpty', true),
    array('alnum'),
    array('stringLength', false, array(6, 20)),
));
?>

If you want to be more verbose or explicit, you can use the array keys 'validator', 'breakChainOnFailure', and 'options':

<?php
$element->addValidators(array(
    array(
        'validator'           => 'NotEmpty',
        'breakChainOnFailure' => true),
    array('validator' => 'alnum'),
    array(
        'validator' => 'stringLength',
        'options'   => array(6, 20)),
));
?>

This usage is good for illustrating how you could then configure validators in a config file:

element.validators.notempty.validator = "NotEmpty"
element.validators.notempty.breakChainOnFailure = true
element.validators.alnum.validator = "Alnum"
element.validators.strlen.validator = "StringLength"
element.validators.strlen.options.min = 6
element.validators.strlen.options.max = 20

Notice that every item has a key, whether or not it needs one; this is a limitation of using configuration files -- but it also helps make explicit what the arguments are for. Just remember that any validator options must be specified in order.

To validate an element, pass the value to isValid():

<?php
if ($element->isValid($value)) {
    // valid
} else {
    // invalid
}
?>

	Validation Operates On Filtered Values
	Zend_Form_Element::isValid() filters values through the provided filter chain prior to validation. See the Filters section for more information.

Validation Context

Zend_Form_Element::isValid() supports an additional argument, $context. Zend_Form::isValid() passes the entire array of data being processed to $context when validating a form, and Zend_Form_Element::isValid(), in turn, passes it to each validator. This means you can write validators that are aware of data passed to other form elements. As an example, consider a standard registration form that has fields for both password and a password confirmation; one validation would be that the two fields match. Such a validator might look like the following: <?php class My_Validate_PasswordConfirmation extends Zend_Validate_Abstract { const NOT_MATCH = 'notMatch'; protected $_messageTemplates = array( self::NOT_MATCH => 'Password confirmation does not match' ); public function isValid($value, $context = null) { $value = (string) $value; $this->_setValue($value); if (is_array($context)) { if (isset($context['password_confirm']) && ($value == $context['password_confirm'])) { return true; } } elseif (is_string($context) && ($value == $context)) { return true; } $this->_error(self::NOT_MATCH); return false; } } ?>

Validators are processed in order. Each validator is processed, unless a validator created with a true breakChainOnFailure value fails its validation. Be sure to specify your validators in a reasonable order.

After a failed validation, you can retrieve the error codes and messages from the validator chain:

<?php
$errors   = $element->getErrors();
$messages = $element->getMessages();
?>

(Note: error messages returned are an associative array of error code / error message pairs.)

In addition to validators, you can specify that an element is required, using setRequired(true). By default, this flag is false, meaning that your validator chain will be skipped if no value is passed to isValid(). You can modify this behavior in a number of ways:

For more information on validators, see the Zend_Validate documentation.

	Using Zend_Form_Elements as general-purpose validators
	Zend_Form_Element implements Zend_Validate_Interface, meaning an element may also be used as a validator in other, non-form related validation chains.

Methods associated with validation include:

One particular pain point for many web developers is the creation of the XHTML forms themselves. For each element, the developer needs to create markup for the element itself, typically a label, and, if they're being nice to their users, markup for displaying validation error messages. The more elements on the page, the less trivial this task becomes.

Zend_Form_Element tries to solve this issue through the use of "decorators". Decorators are simply classes that have access to the element and a method for rendering content. For more information on how decorators work, please see the section on Zend_Form_Decorator.

The default decorators used by Zend_Form_Element are:

	Default Decorators Do Not Need to Be Loaded
	By default, the default decorators are loaded during object initialization. You can disable this by passing the 'disableLoadDefaultDecorators' option to the constructor: <?php $element = new Zend_Form_Element('foo', array('disableLoadDefaultDecorators' => true)); This option may be mixed with any other options you pass, both as array options or in a Zend_Config object.

Since the order in which decorators are registered matters -- first decorator registered is executed first -- you will need to make sure you register your decorators in an appropriate order, or ensure that you set the placement options in a sane fashion. To give an example, here is the code that registers the default decorators:

<?php
$this->addDecorators(array(
    array('ViewHelper'),
    array('Errors'),
    array('HtmlTag', array('tag' => 'dd')),
    array('Label', array('tag' => 'dt')),
));
?>

The initial content is created by the 'ViewHelper' decorator, which creates the form element itself. Next, the 'Errors' decorator fetches error messages from the element, and, if any are present, passes them to the 'FormErrors' view helper to render. The next decorator, 'HtmlTag', wraps the element and errors in an HTML <dd> tag. Finally, the last decorator, 'label', retrieves the element's label and passes it to the 'FormLabel' view helper, wrapping it in an HTML <dt> tag; the value is prepended to the content by default. The resulting output looks basically like this:

<dt><label for="foo" class="optional">Foo</label></dt>
<dd>
    <input type="text" name="foo" id="foo" value="123" />
    <ul class="errors">
        <li>"123" is not an alphanumeric value</li>
    </ul>
</dd>

For more information on decorators, read the Zend_Form_Decorator section.

Using Multiple Decorators of the Same Type

Internally, Zend_Form_Element uses a decorator's class as the lookup mechanism when retrieving decorators. As a result, you cannot register multiple decorators of the same type; subsequent decorators will simply overwrite those that existed before. To get around this, you can use aliases. Instead of passing a decorator or decorator name as the first argument to addDecorator(), pass an array with a single element, with the alias pointing to the decorator object or name: <?php // Alias to 'FooBar': $element->addDecorator(array('FooBar' => 'HtmlTag'), array('tag' => 'div')); // And retrieve later: $decorator = $element->getDecorator('FooBar'); ?> In the addDecorators() and setDecorators() methods, you will need to pass the 'decorator' option in the array representing the decorator: <?php // Add two 'HtmlTag' decorators, aliasing one to 'FooBar': $element->addDecorators( array('HtmlTag', array('tag' => 'div')), array( 'decorator' => array('FooBar' => 'HtmlTag'), 'options' => array('tag' => 'dd') ), ); // And retrieve later: $htmlTag = $element->getDecorator('HtmlTag'); $fooBar = $element->getDecorator('FooBar'); ?>

Methods associated with decorators include:

Zend_Form_Element handles a variety of attributes and element metadata. Basic attributes include:

Form elements may require additional metadata. For XHTML form elements, for instance, you may want to specify attributes such as the class or id. To facilitate this are a set of accessors:

Most of the time, however, you can simply access them as object properties, as Zend_Form_Element utilizes overloading to facilitate access to them:

<?php
// Equivalent to $element->setAttrib('class', 'text'):
$element->class = 'text;
?>

By default, all attributes are passed to the view helper used by the element during rendering, and rendered as HTML attributes of the element tag.

Zend_Form ships with a number of standard elements; please read the Standard Elements chapter for full details.

Zend_Form_Element has many, many methods. What follows is a quick summary of their signatures, grouped by type:

Zend_Form_Element's constructor accepts either an array of options or a Zend_Config object containing options, and it can also be configured using either setOptions() or setConfig(). Generally speaking, keys are named as follows:

Exceptions to the rule include the following:

As an example, here is a config file that passes configuration for every type of configurable data:

[element]
name = "foo"
value = "foobar"
label = "Foo:"
order = 10
required = true
allowEmpty = false
autoInsertNotEmptyValidator = true
description = "Foo elements are for examples"
ignore = false
attribs.id = "foo"
attribs.class = "element"
onclick = "autoComplete(this, '/form/autocomplete/element')" ; sets 'onclick' attribute
prefixPaths.decorator.prefix = "My_Decorator"
prefixPaths.decorator.path = "My/Decorator/"
disableTranslator = 0
validators.required.validator = "NotEmpty"
validators.required.breakChainOnFailure = true
validators.alpha.validator = "alpha"
validators.regex.validator = "regex"
validators.regex.options.pattern = "/^[A-F].*/$"
filters.ucase.filter = "StringToUpper"
decorators.element.decorator = "ViewHelper"
decorators.element.options.helper = "FormText"
decorators.label.decorator = "Label"

You can create your own custom elements by simply extending the Zend_Form_Element class. Common reasons to do so include:

There are two methods typically used to extend an element: init(), which can be used to add custom initialization logic to your element, and loadDefaultDecorators(), which can be used to set a list of default decorators used by your element.

As an example, let's say that all text elements in a form you are creating need to be filtered with StringTrim, validated with a common regular expression, and that you want to use a custom decorator you've created for displaying them, 'My_Decorator_TextItem'; additionally, you have a number of standard attributes, including 'size', 'maxLength', and 'class' you wish to specify. You could define such an element as follows:

<?php class My_Element_Text extends Zend_Form_Element
{
    public function init()
    {
        $this->addPrefixPath('My_Decorator', 'My/Decorator/', 'decorator')
             ->addFilters('StringTrim')
             ->addValidator('Regex', false, array('/^[a-z0-9]{6,}$/i'))
             ->addDecorator('TextItem')
             ->setAttrib('size', 30)
             ->setAttrib('maxLength', 45)
             ->setAttrib('class', 'text');
    }
}
?>

You could then inform your form object about the prefix path for such elements, and start creating elements:

<?php
$form->addPrefixPath('My_Element', 'My/Element/', 'element')
     ->addElement('foo', 'text');
?>

The 'foo' element will now be of type My_Element_Text, and exhibit the behaviour you've outlined.

Another method you may want to override when extending Zend_Form_Element is the loadDefaultDecorators() method. This method conditionally loads a set of default decorators for your element; you may wish to substitute your own decorators in your extending class:

<?php class My_Element_Text extends Zend_Form_Element
{
    public function loadDefaultDecorators()
    {
        $this->addDecorator('ViewHelper')
             ->addDecorator('DisplayError')
             ->addDecorator('Label')
             ->addDecorator('HtmlTag', array('tag' => 'div', 'class' => 'element'));
    }
}
?>

There are many ways to customize elements; be sure to read the API documentation of Zend_Form_Element to know all the methods available.