Form Elements

Introduction

A set of specialized elements are provided for accomplishing application-centric tasks. These include several HTML5 input elements with matching server-side validators, the Csrf element (to prevent Cross Site Request Forgery attacks), and the Captcha element (to display and validate CAPTCHAs).

A Factory is provided to facilitate creation of elements, fieldsets, forms, and the related input filter. See the Zend\Form Quick Start for more information.

Element Base Class

Zend\Form\Element is a base class for all specialized elements and Zend\Form\Fieldset.

Basic Usage

At the bare minimum, each element or fieldset requires a name. You will also typically provide some attributes to hint to the view layer how it might render the item.

use Zend\Form\Element;
use Zend\Form\Form;

$username = new Element\Text('username');
$username
    ->setLabel('Username')
    ->setAttributes(array(
        'class' => 'username',
        'size'  => '30',
    ));

$password = new Element\Password('password');
$password
    ->setLabel('Password')
    ->setAttributes(array(
        'size'  => '30',
    ));

$form = new Form('my-form');
$form
    ->add($username)
    ->add($password);

Public Methods

setName(string $name)

Set the name for this element.

getName()

Return the name for this element.

Return type:string

setValue(string $value)

Set the value for this element.

getValue()

Return the value for this element.

Return type:string

setLabel(string $label)

Set the label content for this element.

getLabel()

Return the label content for this element.

Return type:string

setLabelAttributes(array $labelAttributes)

Set the attributes to use with the label.

getLabelAttributes()

Return the attributes to use with the label.

Return type:array

setOptions(array $options)

Set options for an element. Accepted options are: "label" and "label_attributes", which call setLabel and setLabelAttributes, respectively.

getOptions()

Get defined options for an element

Return type:array

getOption(string $option)

Return the specified option, if defined. If it’s not defined, returns null.

Return type:null|mixed

setAttribute(string $key, mixed $value)

Set a single element attribute.

getAttribute(string $key)

Retrieve a single element attribute.

Return type:mixed

removeAttribute(string $key)

Remove a single attribute

hasAttribute(string $key)

Check if a specific attribute exists for this element.

Return type:boolean

setAttributes(array|Traversable $arrayOrTraversable)

Set many attributes at once. Implementation will decide if this will overwrite or merge.

getAttributes()

Retrieve all attributes at once.

Return type:array|Traversable

removeAttributes(array $keys)

Remove many attributes at once

clearAttributes()

Clear all attributes for this element.

setMessages(array|Traversable $messages)

Set a list of messages to report when validation fails.

getMessages()

Returns a list of validation failure messages, if any.

Return type:array|Traversable

Standard Elements

Button

Zend\Form\Element\Button represents a button form input. It can be used with the Zend\Form\View\Helper\FormButton view helper.

Zend\Form\Element\Button extends from ZendFormElement.

Basic Usage

This element automatically adds a type attribute of value button.

use Zend\Form\Element;
use Zend\Form\Form;

$button = new Element\Button('my-button');
$button->setLabel('My Button')
       ->setValue('foo');

$form = new Form('my-form');
$form->add($button);

Captcha

Zend\Form\Element\Captcha can be used with forms where authenticated users are not necessary, but you want to prevent spam submissions. It is paired with one of the Zend\Form\View\Helper\Captcha\* view helpers that matches the type of CAPTCHA adapter in use.

Basic Usage

A CAPTCHA adapter must be attached in order for validation to be included in the element’s input filter specification. See the section on Zend CAPTCHA Adapters for more information on what adapters are available.

use Zend\Captcha;
use Zend\Form\Element;
use Zend\Form\Form;

$captcha = new Element\Captcha('captcha');
$captcha
    ->setCaptcha(new Captcha\Dumb())
    ->setLabel('Please verify you are human');

$form = new Form('my-form');
$form->add($captcha);

Here is with the array notation:

 use Zend\Captcha;
 use Zend\Form\Form;

 $form = new Form('my-form');
 $form->add(array(
     'type' => 'Zend\Form\Element\Captcha',
     'name' => 'captcha',
     'options' => array(
         'label' => 'Please verify you are human',
         'captcha' => new Captcha\Dumb(),
     ),
 ));

Public Methods

The following methods are in addition to the inherited methods of Zend\Form\Element.

setCaptcha(array|Zend\Captcha\AdapterInterface $captcha)

Set the CAPTCHA adapter for this element. If $captcha is an array, Zend\Captcha\Factory::factory() will be run to create the adapter from the array configuration.

getCaptcha()

Return the CAPTCHA adapter for this element.

Return type:Zend\Captcha\AdapterInterface

getInputSpecification()

Returns a input filter specification, which includes a Zend\Filter\StringTrim filter, and a CAPTCHA validator.

Return type:array

Checkbox

Zend\Form\Element\Checkbox is meant to be paired with the Zend\Form\View\Helper\FormCheckbox for HTML inputs with type checkbox. This element adds an InArray validator to its input filter specification in order to validate on the server if the checkbox contains either the checked value or the unchecked value.

Basic Usage

This element automatically adds a "type" attribute of value "checkbox".

use Zend\Form\Element;
use Zend\Form\Form;

$checkbox = new Element\Checkbox('checkbox');
$checkbox->setLabel('A checkbox');
$checkbox->setUseHiddenElement(true);
$checkbox->setCheckedValue("good");
$checkbox->setUncheckedValue("bad");

$form = new Form('my-form');
$form->add($checkbox);

Using the array notation:

use Zend\Form\Form;

$form = new Form('my-form');
$form->add(array(
    'type' => 'Zend\Form\Element\Checkbox',
    'name' => 'checkbox',
    'options' => array(
        'label' => 'A checkbox',
        'use_hidden_element' => true,
        'checked_value' => 'good',
        'unchecked_value' => 'bad'
    )
));

Public Methods

The following methods are in addition to the inherited methods of Zend\Form\Element .

setOptions(array $options)

Set options for an element of type Checkbox. Accepted options, in addition to the inherited options of Zend\Form\Element , are: "use_hidden_element", "checked_value" and "unchecked_value" , which call setUseHiddenElement, setCheckedValue and setUncheckedValue , respectively.

setUseHiddenElement(boolean $useHiddenElement)

If set to true (which is default), the view helper will generate a hidden element that contains the unchecked value. Therefore, when using custom unchecked value, this option have to be set to true.

useHiddenElement()

Return if a hidden element is generated.

Return type:boolean

setCheckedValue(string $checkedValue)

Set the value to use when the checkbox is checked.

getCheckedValue()

Return the value used when the checkbox is checked.

Return type:string

setUncheckedValue(string $uncheckedValue)

Set the value to use when the checkbox is unchecked. For this to work, you must make sure that use_hidden_element is set to true.

getUncheckedValue()

Return the value used when the checkbox is unchecked.

Return type:string

getInputSpecification()

Returns a input filter specification, which includes a Zend\Validator\InArray to validate if the value is either checked value or unchecked value.

Return type:array

isChecked()

Checks if the checkbox is checked.

Return type:boolean

setChecked(bool $value)

Checks or unchecks the checkbox.

Collection

Sometimes, you may want to add input (or a set of inputs) multiple times, either because you don’t want to duplicate code, or because you do not know in advance how many elements you will need (in the case of elements dynamically added to a form using JavaScript, for instance). For more information about Collection, please refer to the Form Collections tutorial.

Zend\Form\Element\Collection is meant to be paired with the Zend\Form\View\Helper\FormCollection.

Basic Usage

use Zend\Form\Element;
use Zend\Form\Form;

$colors = new Element\Collection('collection');
$colors->setLabel('Colors');
$colors->setCount(2);
$colors->setTargetElement(new Element\Color());
$colors->setShouldCreateTemplate(true);

$form = new Form('my-form');
$form->add($colors);

Using the array notation:

use Zend\Form\Element;
use Zend\Form\Form;

$form = new Form('my-form');
$form->add(array(
    'type' => 'Zend\Form\Element\Collection',
    'options' => array(
        'label' => 'Colors',
        'count' => 2,
        'should_create_template' => true,
        'target_element' => new Element\Color()
    )
));

Public Methods

The following methods are in addition to the inherited methods of Zend\Form\Element .

setOptions(array $options)

Set options for an element of type Collection. Accepted options, in addition to the inherited options of Zend\Form\Element , are: "target_element", "count", "allow_add", "allow_remove", "should_create_template" and "template_placeholder". Those option keys respectively call call setTargetElement, setCount, setAllowAdd, setAllowRemove, setShouldCreateTemplate and setTemplatePlaceholder.

allowObjectBinding(object $object)

Checks if the object can be set in this fieldset.

Return type:bool

setObject(array|Traversable $object)

Set the object used by the hydrator. In this case the “object” is a collection of objects.

populateValues(array|Traversable $data)

Populate values

allowValueBinding()

Checks if this fieldset can bind data

Return type:bool

setCount($count)

Defines how many times the target element will be initially rendered by the Zend\Form\View\Helper\FormCollection view helper.

getCount()

Return the number of times the target element will be initially rendered by the Zend\Form\View\Helper\FormCollection view helper.

Return type:integer

setTargetElement($elementOrFieldset)

This function either takes an Zend\Form\ElementInterface, Zend\Form\FieldsetInterface instance or an array to pass to the form factory. When the Collection element will be validated, the input filter will be retrieved from this target element and be used to validate each element in the collection.

getTargetElement()

Return the target element used by the collection.

Return type:ElementInterface | null

setAllowAdd($allowAdd)

If allowAdd is set to true (which is the default), new elements added dynamically in the form (using JavaScript, for instance) will also be validated and retrieved.

allowAdd()

Return if new elements can be dynamically added in the collection.

Return type:boolean

setAllowRemove($allowRemove)

If allowRemove is set to true (which is the default), new elements added dynamically in the form (using JavaScript, for instance) will be allowed to be removed.

allowRemove()

Return if new elements can be dynamically removed from the collection.

Return type:boolean

setShouldCreateTemplate($shouldCreateTemplate)

If shouldCreateTemplate is set to true (defaults to false), a <span> element will be generated by the Zend\Form\View\Helper\FormCollection view helper. This non-semantic span element contains a single data-template HTML5 attribute whose value is the whole HTML to copy to create a new element in the form. The template is indexed using the templatePlaceholder value.

shouldCreateTemplate()

Return if a template should be created.

Return type:boolean

setTemplatePlaceholder($templatePlaceholder)

Set the template placeholder (defaults to __index__) used to index element in the template.

getTemplatePlaceholder()

Returns the template placeholder used to index element in the template.

Return type:string

getTemplateElement()

Get a template element used for rendering purposes only

Return type:null|ElementInterface|FieldsetInterface

prepareElement()

Prepare the collection by adding a dummy template element if the user want one

prepareFieldset()

If both count and targetElement are set, add them to the fieldset

Csrf

Zend\Form\Element\Csrf pairs with the Zend\Form\View\Helper\FormHidden to provide protection from CSRF attacks on forms, ensuring the data is submitted by the user session that generated the form and not by a rogue script. Protection is achieved by adding a hash element to a form and verifying it when the form is submitted.

Basic Usage

This element automatically adds a "type" attribute of value "hidden".

use Zend\Form\Element;
use Zend\Form\Form;

$csrf = new Element\Csrf('csrf');

$form = new Form('my-form');
$form->add($csrf);

You can change the options of the CSRF validator using the setCsrfValidatorOptions function, or by using the "csrf_options" key. Here is an example using the array notation:

 use Zend\Form\Form;

 $form = new Form('my-form');
 $form->add(array(
     'type' => 'Zend\Form\Element\Csrf',
     'name' => 'csrf',
     'options' => array(
             'csrf_options' => array(
                     'timeout' => 600
             )
     )
 ));

Public Methods

The following methods are in addition to the inherited methods of Zend\Form\Element.

getInputSpecification()

Returns a input filter specification, which includes a Zend\Filter\StringTrim filter and a Zend\Validator\Csrf to validate the CSRF value.

Return type:array

setCsrfValidatorOptions(array $options)

Set the options that are used by the CSRF validator.

getCsrfValidatorOptions()

Get the options that are used by the CSRF validator.

Return type:array

setCsrfValidator(ZendValidatorCsrf $validator)

Override the default CSRF validator by setting another one.

getCsrfValidator()

Get the CSRF validator.

Return type:ZendValidatorCsrf

File

Zend\Form\Element\File represents a form file input and provides a default input specification with a type of FileInput (important for handling validators and filters correctly). It can be used with the Zend\Form\View\Helper\FormFile view helper.

Zend\Form\Element\File extends from Zend\Form\Element.

Basic Usage

This element automatically adds a "type" attribute of value "file". It will also set the form’s enctype to multipart/form-data during $form->prepare().

use Zend\Form\Element;
use Zend\Form\Form;

// Single file upload
$file = new Element\File('file');
$file->setLabel('Single file input');

// HTML5 multiple file upload
$multiFile = new Element\File('multi-file');
$multiFile->setLabel('Multi file input')
          ->setAttribute('multiple', true);

$form = new Form('my-file');
$form->add($file)
     ->add($multiFile);

Hidden

Zend\Form\Element\Hidden represents a hidden form input. It can be used with the Zend\Form\View\Helper\FormHidden view helper.

Zend\Form\Element\Hidden extends from Zend\Form\Element.

Basic Usage

This element automatically adds a "type" attribute of value "hidden".

use Zend\Form\Element;
use Zend\Form\Form;

$hidden = new Element\Hidden('my-hidden');
$hidden->setValue('foo');

$form = new Form('my-form');
$form->add($hidden);

Here is with the array notation:

 use Zend\Form\Form;

 $form = new Form('my-form');
 $form->add(array(
     'type' => 'Zend\Form\Element\Hidden',
     'name' => 'my-hidden',
     'attributes' => array(
             'value' => 'foo'
     )
 ));

Image

Zend\Form\Element\Image represents a image button form input. It can be used with the Zend\Form\View\Helper\FormImage view helper.

Zend\Form\Element\Image extends from Zend\Form\Element.

Basic Usage

This element automatically adds a "type" attribute of value "image".

use Zend\Form\Element;
use Zend\Form\Form;

$image = new Element\Image('my-image');
$image->setAttribute('src', 'http://my.image.url'); // Src attribute is required

$form = new Form('my-form');
$form->add($image);

Month Select

Zend\Form\Element\MonthSelect is meant to be paired with the Zend\Form\View\Helper\FormMonthSelect. This element creates two select elements, where the first one is populated with months and the second is populated with years. By default, it sets 100 years in the past for the year element, starting with the current year.

Basic Usage

use Zend\Form\Element;
use Zend\Form\Form;

$monthYear = new Element\MonthSelect('monthyear');
$monthYear->setLabel('Select a month and a year');
$monthYear->setMinYear(1986);

$form = new Form('dateselect');
$form->add($monthYear);

Using the array notation:

use Zend\Form\Form;

$form = new Form('dateselect');
$form->add(array(
    'type' => 'Zend\Form\Element\MonthSelect',
    'name' => 'monthyear',
    'options' => array(
        'label' => 'Select a month and a year',
        'min_year' => 1986,
    )
));

Public Methods

The following methods are in addition to the inherited methods of Zend\Form\Element.

getMonthElement()

Returns the Select element that is used for the months part.

Return type:Zend\Form\Element\Select

getYearElement()

Returns the Select element that is used for the years part.

Return type:Zend\Form\Element\Select

setMonthAttributes(array $monthAttributes)

Set attributes on the Select element that is used for the months part.

getMonthAttributes()

Get attributes on the Select element that is used for the months part.

Return type:array

setYearAttributes(array $yearAttributes)

Set attributes on the Select element that is used for the years part.

getYearAttributes()

Get attributes on the Select element that is used for the years part.

Return type:array

setMinYear(int $minYear)

Set the minimum year.

getMinYear()

Get the minimum year.

setMaxYear(int $maxYear)

Set the maximum year.

getMaxYear()

Get the maximum year.

setValue(mixed $value)

Set the value for the MonthSelect element.

If the value is an instance of \DateTime, it will use the month and year values from that date. Otherwise, the value should be an associative array with the month key for the month value, and with the year key for the year value.

MultiCheckbox

Zend\Form\Element\MultiCheckbox is meant to be paired with the Zend\Form\View\Helper\FormMultiCheckbox for HTML inputs with type checkbox. This element adds an InArray validator to its input filter specification in order to validate on the server if the checkbox contains values from the multiple checkboxes.

Basic Usage

This element automatically adds a "type" attribute of value "checkbox" for every checkboxes.

     use Zend\Form\Element;
     use Zend\Form\Form;

     $multiCheckbox = new Element\MultiCheckbox('multi-checkbox');
     $multiCheckbox->setLabel('What do you like ?');
     $multiCheckbox->setValueOptions(array(
                     '0' => 'Apple',
                     '1' => 'Orange',
                     '2' => 'Lemon'
     ));

     $form = new Form('my-form');
     $form->add($multiCheckbox);

Using the array notation:

 use Zend\Form\Form;

     $form = new Form('my-form');
     $form->add(array(
             'type' => 'Zend\Form\Element\MultiCheckbox',
             'name' => 'multi-checkbox',
             'options' => array(
                     'label' => 'What do you like ?',
                     'value_options' => array(
                             '0' => 'Apple',
                             '1' => 'Orange',
                             '2' => 'Lemon',
                     ),
             )
     ));

Public Methods

The following methods are in addition to the inherited methods of Zend\Form\Element\Checkbox .

setOptions(array $options)

Set options for an element of type Checkbox. Accepted options, in addition to the inherited options of Zend\Form\Element\Checkbox , are: "value_options", which call setValueOptions.

setValueOptions(array $options)

Set the value options for every checkbox of the multi-checkbox. The array must contain a key => value for every checkbox.

getValueOptions()

Return the value options.

Return type:array

Password

Zend\Form\Element\Password represents a password form input. It can be used with the Zend\Form\View\Helper\FormPassword view helper.

Zend\Form\Element\Password extends from Zend\Form\Element.

Basic Usage

This element automatically adds a "type" attribute of value "password".

use Zend\Form\Element;
use Zend\Form\Form;

$password = new Element\Password('my-password');
$password->setLabel('Enter your password');

$form = new Form('my-form');
$form->add($password);

Radio

Zend\Form\Element\Radio is meant to be paired with the Zend\Form\View\Helper\FormRadio for HTML inputs with type radio. This element adds an InArray validator to its input filter specification in order to validate on the server if the value is contains within the radio value elements.

Basic Usage

This element automatically adds a "type" attribute of value "radio" for every radio.

     use Zend\Form\Element;
     use Zend\Form\Form;

     $radio = new Element\Radio('gender');
     $radio->setLabel('What is your gender ?');
     $radio->setValueOptions(array(
                     '0' => 'Female',
                     '1' => 'Male',
     ));

     $form = new Form('my-form');
     $form->add($radio);

Using the array notation:

 use Zend\Form\Form;

     $form = new Form('my-form');
     $form->add(array(
             'type' => 'Zend\Form\Element\Radio',
             'name' => 'gender',
             'options' => array(
                     'label' => 'What is your gender ?',
                     'value_options' => array(
                             '0' => 'Female',
                             '1' => 'Male',
                     ),
             )
     ));

Public Methods

All the methods from the inherited methods of Zend\Form\Element\MultiCheckbox are also available for this element.

Select

Zend\Form\Element\Select is meant to be paired with the Zend\Form\View\Helper\FormSelect for HTML inputs with type select. This element adds an InArray validator to its input filter specification in order to validate on the server if the selected value belongs to the values. This element can be used as a multi-select element by adding the “multiple” HTML attribute to the element.

Basic Usage

This element automatically adds a "type" attribute of value "select".

     use Zend\Form\Element;
     use Zend\Form\Form;

     $select = new Element\Select('language');
     $select->setLabel('Which is your mother tongue?');
     $select->setValueOptions(array(
             '0' => 'French',
             '1' => 'English',
             '2' => 'Japanese',
             '3' => 'Chinese',
     ));

     $form = new Form('language');
     $form->add($select);

Using the array notation:

 use Zend\Form\Form;

     $form = new Form('my-form');
     $form->add(array(
             'type' => 'Zend\Form\Element\Select',
             'name' => 'language',
             'options' => array(
                     'label' => 'Which is your mother tongue?',
                     'value_options' => array(
                             '0' => 'French',
                             '1' => 'English',
                             '2' => 'Japanese',
                             '3' => 'Chinese',
                     ),
             )
     ));

You can add an empty option (option with no value) using the "empty_option" option:

 use Zend\Form\Form;

     $form = new Form('my-form');
     $form->add(array(
             'type' => 'Zend\Form\Element\Select',
             'name' => 'language',
             'options' => array(
                     'label' => 'Which is your mother tongue?',
                     'empty_option' => 'Please choose your language',
                     'value_options' => array(
                             '0' => 'French',
                             '1' => 'English',
                             '2' => 'Japanese',
                             '3' => 'Chinese',
                     ),
             )
     ));

Option groups are also supported. You just need to add an ‘options’ key to the value options.

     use Zend\Form\Element;
     use Zend\Form\Form;

     $select = new Element\Select('language');
     $select->setLabel('Which is your mother tongue?');
     $select->setValueOptions(array(
      'european' => array(
         'label' => 'European languages',
         'options' => array(
            '0' => 'French',
            '1' => 'Italian',
         ),
      ),
      'asian' => array(
         'label' => 'Asian languages',
         'options' => array(
            '2' => 'Japanese',
            '3' => 'Chinese',
         ),
      ),
     ));

     $form = new Form('language');
     $form->add($select);

Public Methods

The following methods are in addition to the inherited methods of Zend\Form\Element .

setOptions(array $options)

Set options for an element of type Checkbox. Accepted options, in addition to the inherited options of Zend\Form\Element\Checkbox , are: "value_options" and "empty_option", which call setValueOptions and setEmptyOption, respectively.

setValueOptions(array $options)

Set the value options for the select element. The array must contain key => value pairs.

getValueOptions()

Return the value options.

Return type:array

setEmptyOption($emptyOption)

Optionally set a label for an empty option (option with no value). It is set to “null” by default, which means that no empty option will be rendered.

getEmptyOption()

Get the label for the empty option (null if none).

Return type:string|null

Submit

Zend\Form\Element\Submit represents a submit button form input. It can be used with the Zend\Form\View\Helper\FormSubmit view helper.

Zend\Form\Element\Submit extends from Zend\Form\Element.

Basic Usage

This element automatically adds a "type" attribute of value "submit".

use Zend\Form\Element;
use Zend\Form\Form;

$submit = new Element\Submit('my-submit');
$submit->setValue('Submit Form');

$form = new Form('my-form');
$form->add($submit);

Text

Zend\Form\Element\Text represents a text form input. It can be used with the Zend\Form\View\Helper\FormText view helper.

Zend\Form\Element\Text extends from Zend\Form\Element.

Basic Usage

This element automatically adds a "type" attribute of value "text".

use Zend\Form\Element;
use Zend\Form\Form;

$text = new Element\Text('my-text');
$text->setLabel('Enter your name');

$form = new Form('my-form');
$form->add($text);

Textarea

Zend\Form\Element\Textarea represents a textarea form input. It can be used with the Zend\Form\View\Helper\FormTextarea view helper.

Zend\Form\Element\Textarea extends from Zend\Form\Element.

Basic Usage

This element automatically adds a "type" attribute of value "textarea".

use Zend\Form\Element;
use Zend\Form\Form;

$textarea = new Element\Textarea('my-textarea');
$textarea->setLabel('Enter a description');

$form = new Form('my-form');
$form->add($textarea);

HTML5 Elements

Color

Zend\Form\Element\Color is meant to be paired with the Zend\Form\View\Helper\FormColor for HTML5 inputs with type color. This element adds filters and a Regex validator to it’s input filter specification in order to validate a HTML5 valid simple color value on the server.

Basic Usage

This element automatically adds a "type" attribute of value "color".

use Zend\Form\Element;
use Zend\Form\Form;

$color = new Element\Color('color');
$color->setLabel('Background color');

$form = new Form('my-form');
$form->add($color);

Here is the same example using the array notation:

 use Zend\Form\Form;

 $form = new Form('my-form');
 $form->add(array(
     'type' => 'Zend\Form\Element\Color',
     'name' => 'color',
     'options' => array(
             'label' => 'Background color'
     )
 ));

Public Methods

The following methods are in addition to the inherited methods of Zend\Form\Element.

getInputSpecification()

Returns a input filter specification, which includes Zend\Filter\StringTrim and Zend\Filter\StringToLower filters, and a Zend\Validator\Regex to validate the RGB hex format.

Return type:array

Date

Zend\Form\Element\Date is meant to be paired with the Zend\Form\View\Helper\FormDate for HTML5 inputs with type date. This element adds filters and validators to it’s input filter specification in order to validate HTML5 date input values on the server.

Basic Usage

This element automatically adds a "type" attribute of value "date".

use Zend\Form\Element;
use Zend\Form\Form;

$date = new Element\Date('appointment-date');
$date
    ->setLabel('Appointment Date')
    ->setAttributes(array(
        'min'  => '2012-01-01',
        'max'  => '2020-01-01',
        'step' => '1', // days; default step interval is 1 day
    ))
    ->setOptions(array(
        'format' => 'Y-m-d'
    ));

$form = new Form('my-form');
$form->add($date);

Here is with the array notation:

 use Zend\Form\Form;

 $form = new Form('my-form');
 $form->add(array(
     'type' => 'Zend\Form\Element\Date',
     'name' => 'appointment-date',
     'options' => array(
             'label' => 'Appointment Date',
             'format' => 'Y-m-d'
     ),
     'attributes' => array(
             'min' => '2012-01-01',
             'max' => '2020-01-01',
             'step' => '1', // days; default step interval is 1 day
     )
 ));

Note

Note: the min, max, and step attributes should be set prior to calling Zend\Form::prepare(). Otherwise, the default input specification for the element may not contain the correct validation rules.

Public Methods

The following methods are in addition to the inherited methods of Zend\Form\Element\DateTime.

getInputSpecification()

Returns a input filter specification, which includes Zend\Filter\StringTrim and will add the appropriate validators based on the values from the min, max, and step attributes and format option. See getInputSpecification in Zend\Form\Element\DateTime for more information.

One difference from Zend\Form\Element\DateTime is that the Zend\Validator\DateStep validator will expect the step attribute to use an interval of days (default is 1 day).

Return type:array

DateTime

Zend\Form\Element\DateTime is meant to be paired with the Zend\Form\View\Helper\FormDateTime for HTML5 inputs with type datetime. This element adds filters and validators to it’s input filter specification in order to validate HTML5 datetime input values on the server.

Basic Usage

This element automatically adds a "type" attribute of value "datetime".

use Zend\Form\Element;
use Zend\Form\Form;

$dateTime = new Element\DateTime('appointment-date-time');
$dateTime
    ->setLabel('Appointment Date/Time')
    ->setAttributes(array(
        'min'  => '2010-01-01T00:00:00Z',
        'max'  => '2020-01-01T00:00:00Z',
        'step' => '1', // minutes; default step interval is 1 min
    ))
    ->setOptions(array(
        'format' => 'Y-m-d\TH:iP'
    ));

$form = new Form('my-form');
$form->add($dateTime);

Here is with the array notation:

 use Zend\Form\Form;

 $form = new Form('my-form');
 $form->add(array(
     'type' => 'Zend\Form\Element\DateTime',
     'name' => 'appointment-date-time',
     'options' => array(
             'label' => 'Appointment Date/Time',
             'format' => 'Y-m-d\TH:iP'
     ),
     'attributes' => array(
             'min' => '2010-01-01T00:00:00Z',
             'max' => '2020-01-01T00:00:00Z',
             'step' => '1', // minutes; default step interval is 1 min
     )
 ));

Note

Note: the min, max, and step attributes should be set prior to calling Zend\Form::prepare(). Otherwise, the default input specification for the element may not contain the correct validation rules.

Public Methods

The following methods are in addition to the inherited methods of Zend\Form\Element.

getInputSpecification()

Returns a input filter specification, which includes Zend\Filter\StringTrim and will add the appropriate validators based on the values from the min, max, and step attributes and format option.

If the min attribute is set, a Zend\Validator\GreaterThan validator will be added to ensure the date value is greater than the minimum value.

If the max attribute is set, a Zend\Validator\LessThanValidator validator will be added to ensure the date value is less than the maximum value.

If the step attribute is set to “any”, step validations will be skipped. Otherwise, a Zend\Validator\DateStep validator will be added to ensure the date value is within a certain interval of minutes (default is 1 minute).

The input filter specification also includes a Zend\Validator\Date validator to ensure the format of the value. If the format option is set, that format will be used. Otherwise the default format will be used.

Return type:array

setOptions(array $options)

Set options for an element of type DateTime. The accepted option, in addition to the inherited options of Zend\Form\Element , is: "format", which calls setFormat.

setFormat(string $format)

Sets the format used to validate the value. Accepts a \DateTime compatible string.

getFormat()

Return the DateTime format used to validate the value.

Return type:String

DateTimeLocal

Zend\Form\Element\DateTimeLocal is meant to be paired with the Zend\Form\View\Helper\FormDateTimeLocal for HTML5 inputs with type datetime-local. This element adds filters and validators to it’s input filter specification in order to validate HTML5 a local datetime input values on the server.

Basic Usage

This element automatically adds a "type" attribute of value "datetime-local".

use Zend\Form\Element;
use Zend\Form\Form;

$dateTimeLocal = new Element\DateTimeLocal('appointment-date-time');
$dateTimeLocal
    ->setLabel('Appointment Date')
    ->setAttributes(array(
        'min'  => '2010-01-01T00:00:00',
        'max'  => '2020-01-01T00:00:00',
        'step' => '1', // minutes; default step interval is 1 min
    ))
    ->setOptions(array(
        'format' => 'Y-m-d\TH:i'
    ));

$form = new Form('my-form');
$form->add($dateTimeLocal);

Here is with the array notation:

 use Zend\Form\Form;

 $form = new Form('my-form');
 $form->add(array(
     'type' => 'Zend\Form\Element\DateTimeLocal',
     'name' => 'appointment-date-time',
     'options' => array(
             'label'  => 'Appointment Date',
             'format' => 'Y-m-d\TH:i'
     ),
     'attributes' => array(
             'min' => '2010-01-01T00:00:00',
             'max' => '2020-01-01T00:00:00',
             'step' => '1', // minutes; default step interval is 1 min
     )
 ));

Note

Note: the min, max, and step attributes should be set prior to calling Zend\Form::prepare(). Otherwise, the default input specification for the element may not contain the correct validation rules.

Public Methods

The following methods are in addition to the inherited methods of Zend\Form\Element\DateTime.

getInputSpecification()

Returns a input filter specification, which includes Zend\Filter\StringTrim and will add the appropriate validators based on the values from the min, max, and step attributes and format option. See getInputSpecification in Zend\Form\Element\DateTime for more information.

Return type:array

Email

Zend\Form\Element\Email is meant to be paired with the Zend\Form\View\Helper\FormEmail for HTML5 inputs with type email. This element adds filters and validators to it’s input filter specification in order to validate HTML5 valid email address on the server.

Basic Usage

This element automatically adds a "type" attribute of value "email".

use Zend\Form\Element;
use Zend\Form\Form;

$form = new Form('my-form');

// Single email address
$email = new Element\Email('email');
$email->setLabel('Email Address')
$form->add($email);

// Comma separated list of emails
$emails = new Element\Email('emails');
$emails
    ->setLabel('Email Addresses')
    ->setAttribute('multiple', true);
$form->add($emails);

Here is with the array notation:

 use Zend\Form\Form;

 $form = new Form('my-form');
 $form->add(array(
     'type' => 'Zend\Form\Element\Email',
     'name' => 'email',
     'options' => array(
         'label' => 'Email Address'
     ),
 ));

 $form->add(array(
     'type' => 'Zend\Form\Element\Email',
     'name' => 'emails',
     'options' => array(
             'label' => 'Email Addresses'
     ),
     'attributes' => array(
         'multiple' => true
     )
 ));

Note

Note: the multiple attribute should be set prior to calling Zend\Form::prepare(). Otherwise, the default input specification for the element may not contain the correct validation rules.

Public Methods

The following methods are in addition to the inherited methods of Zend\Form\Element.

getInputSpecification()

Returns a input filter specification, which includes a Zend\Filter\StringTrim filter, and a validator based on the multiple attribute.

If the multiple attribute is unset or false, a Zend\Validator\Regex validator will be added to validate a single email address.

If the multiple attribute is true, a Zend\Validator\Explode validator will be added to ensure the input string value is split by commas before validating each email address with Zend\Validator\Regex.

Return type:array

setValidator(ValidatorInterface $validator)

Sets the primary validator to use for this element

getValidator()

Get the primary validator

Return type:ValidatorInterface

setEmailValidator(ValidatorInterface $validator)

Sets the email validator to use for multiple or single email addresses.

getEmailValidator()

Get the email validator to use for multiple or single email addresses.

The default Regex validator in use is to match that of the browser validation, but you are free to set a different (more strict) email validator such as Zend\Validator\Email if you wish.

Month

Zend\Form\Element\Month is meant to be paired with the Zend\Form\View\Helper\FormMonth for HTML5 inputs with type month. This element adds filters and validators to it’s input filter specification in order to validate HTML5 month input values on the server.

Basic Usage

This element automatically adds a "type" attribute of value "month".

use Zend\Form\Element;
use Zend\Form\Form;

$month = new Element\Month('month');
$month
    ->setLabel('Month')
    ->setAttributes(array(
        'min'  => '2012-01',
        'max'  => '2020-01',
        'step' => '1', // months; default step interval is 1 month
    ));

$form = new Form('my-form');
$form->add($month);

Here is with the array notation:

 use Zend\Form\Form;

 $form = new Form('my-form');
 $form->add(array(
     'type' => 'Zend\Form\Element\Month',
     'name' => 'month',
     'options' => array(
             'label' => 'Month'
     ),
     'attributes' => array(
             'min' => '2012-12',
             'max' => '2020-01',
             'step' => '1', // months; default step interval is 1 month
     )
 ));

Note

Note: the min, max, and step attributes should be set prior to calling Zend\Form::prepare(). Otherwise, the default input specification for the element may not contain the correct validation rules.

Public Methods

The following methods are in addition to the inherited methods of Zend\Form\Element\DateTime.

getInputSpecification()

Returns a input filter specification, which includes Zend\Filter\StringTrim and will add the appropriate validators based on the values from the min, max, and step attributes. See getInputSpecification in Zend\Form\Element\DateTime for more information.

One difference from Zend\Form\Element\DateTime is that the Zend\Validator\DateStep validator will expect the step attribute to use an interval of months (default is 1 month).

Return type:array

Number

Zend\Form\Element\Number is meant to be paired with the Zend\Form\View\Helper\FormNumber for HTML5 inputs with type number. This element adds filters and validators to it’s input filter specification in order to validate HTML5 number input values on the server.

Basic Usage

This element automatically adds a "type" attribute of value "number".

use Zend\Form\Element;
use Zend\Form\Form;

$number = new Element\Number('quantity');
$number
    ->setLabel('Quantity')
    ->setAttributes(array(
        'min'  => '0',
        'max'  => '10',
        'step' => '1', // default step interval is 1
    ));

$form = new Form('my-form');
$form->add($number);

Here is with the array notation:

 use Zend\Form\Form;

 $form = new Form('my-form');
 $form->add(array(
     'type' => 'Zend\Form\Element\Number',
     'name' => 'quantity',
     'options' => array(
             'label' => 'Quantity'
     ),
     'attributes' => array(
             'min' => '0',
             'max' => '10',
             'step' => '1', // default step interval is 1
     )
 ));

Note

Note: the min, max, and step attributes should be set prior to calling Zend\Form::prepare(). Otherwise, the default input specification for the element may not contain the correct validation rules.

Public Methods

The following methods are in addition to the inherited methods of Zend\Form\Element.

getInputSpecification()

Returns a input filter specification, which includes Zend\Filter\StringTrim and will add the appropriate validators based on the values from the min, max, and step attributes.

If the min attribute is set, a Zend\Validator\GreaterThan validator will be added to ensure the number value is greater than the minimum value. The min value should be a valid floating point number.

If the max attribute is set, a Zend\Validator\LessThan validator will be added to ensure the number value is less than the maximum value. The max value should be a valid floating point number.

If the step attribute is set to “any”, step validations will be skipped. Otherwise, a Zend\Validator\Step validator will be added to ensure the number value is within a certain interval (default is 1). The step value should be either “any” or a valid floating point number.

Return type:array

Range

Zend\Form\Element\Range is meant to be paired with the Zend\Form\View\Helper\FormRange for HTML5 inputs with type range. This element adds filters and validators to it’s input filter specification in order to validate HTML5 range values on the server.

Basic Usage

This element automatically adds a "type" attribute of value "range".

use Zend\Form\Element;
use Zend\Form\Form;

$range = new Element\Range('range');
$range
    ->setLabel('Minimum and Maximum Amount')
    ->setAttributes(array(
        'min'  => '0',   // default minimum is 0
        'max'  => '100', // default maximum is 100
        'step' => '1',   // default interval is 1
    ));

$form = new Form('my-form');
$form->add($range);

Here is with the array notation:

 use Zend\Form\Form;

 $form = new Form('my-form');
 $form->add(array(
     'type' => 'Zend\Form\Element\Range',
     'name' => 'range',
     'options' => array(
             'label' => 'Minimum and Maximum Amount'
     ),
     'attributes' => array(
             'min' => 0, // default minimum is 0
             'max' => 100, // default maximum is 100
             'step' => 1 // default interval is 1
     )
 ));

Note

Note: the min, max, and step attributes should be set prior to calling Zend\Form::prepare(). Otherwise, the default input specification for the element may not contain the correct validation rules.

Public Methods

The following methods are in addition to the inherited methods of Zend\Form\Element\Number.

getInputSpecification()

Returns a input filter specification, which includes Zend\Filter\StringTrim and will add the appropriate validators based on the values from the min, max, and step attributes. See getInputSpecification in Zend\Form\Element\Number for more information.

The Range element differs from Zend\Form\Element\Number in that the Zend\Validator\GreaterThan and Zend\Validator\LessThan validators will always be present. The default minimum is 1, and the default maximum is 100.

Return type:array

Time

Zend\Form\Element\Time is meant to be paired with the Zend\Form\View\Helper\FormTime for HTML5 inputs with type time. This element adds filters and validators to it’s input filter specification in order to validate HTML5 time input values on the server.

Basic Usage

This element automatically adds a "type" attribute of value "time".

use Zend\Form\Element;
use Zend\Form\Form;

$time = new Element\Time('time');
$time
    ->setLabel('Time')
    ->setAttributes(array(
        'min'  => '00:00:00',
        'max'  => '23:59:59',
        'step' => '60', // seconds; default step interval is 60 seconds
    ))
    ->setOptions(array(
        'format' => 'H:i:s'
    ));

$form = new Form('my-form');
$form->add($time);

Here is the same example using the array notation:

 use Zend\Form\Form;

 $form = new Form('my-form');
 $form->add(array(
     'type' => 'Zend\Form\Element\Time',
     'name' => 'time',
     'options'=> array(
             'label'  => 'Time',
             'format' => 'H:i:s'
     ),
     'attributes' => array(
             'min' => '00:00:00',
             'max' => '23:59:59',
             'step' => '60', // seconds; default step interval is 60 seconds
     )
 ));

Note

The min, max, and step attributes should be set prior to calling Zend\Form::prepare(). Otherwise, the default input specification for the element may not contain the correct validation rules.

Note

The default date format for the validator is H:i:s. A valid time string is however not required to have a seconds part. In fact some user agent UIs such as Google Chrome and Opera submits a value on the H:i format (i.e. without a second part). You might therefore want to set the date format accordingly.

Public Methods

The following methods are in addition to the inherited methods of Zend\Form\Element\DateTime.

getInputSpecification()

Returns a input filter specification, which includes Zend\Filter\StringTrim and will add the appropriate validators based on the values from the min, max, and step attributes and format option. See getInputSpecification in Zend\Form\Element\DateTime for more information.

One difference from Zend\Form\Element\DateTime is that the Zend\Validator\DateStep validator will expect the step attribute to use an interval of seconds (default is 60 seconds).

Return type:array

Url

Zend\Form\Element\Url is meant to be paired with the Zend\Form\View\Helper\FormUrl for HTML5 inputs with type url. This element adds filters and a Zend\Validator\Uri validator to it’s input filter specification for validating HTML5 URL input values on the server.

Basic Usage

This element automatically adds a "type" attribute of value "url".

use Zend\Form\Element;
use Zend\Form\Form;

$url = new Element\Url('webpage-url');
$url->setLabel('Webpage URL');

$form = new Form('my-form');
$form->add($url);

Here is the same example using the array notation:

 use Zend\Form\Form;

 $form = new Form('my-form');
 $form->add(array(
     'type' => 'Zend\Form\Element\Url',
     'name' => 'webpage-url',
     'options' => array(
             'label' => 'Webpage URL'
     )
 ));

Public Methods

The following methods are in addition to the inherited methods of Zend\Form\Element.

getInputSpecification()

Returns a input filter specification, which includes a Zend\Filter\StringTrim filter, and a Zend\Validator\Uri to validate the URI string.

Return type:array

Week

Zend\Form\Element\Week is meant to be paired with the Zend\Form\View\Helper\FormWeek for HTML5 inputs with type week. This element adds filters and validators to it’s input filter specification in order to validate HTML5 week input values on the server.

Basic Usage

This element automatically adds a "type" attribute of value "week".

use Zend\Form\Element;
use Zend\Form\Form;

$week = new Element\Week('week');
$week
    ->setLabel('Week')
    ->setAttributes(array(
        'min'  => '2012-W01',
        'max'  => '2020-W01',
        'step' => '1', // weeks; default step interval is 1 week
    ));

$form = new Form('my-form');
$form->add($week);

Here is the same example using the array notation:

 use Zend\Form\Form;

 $form = new Form('my-form');
 $form->add(array(
     'type' => 'Zend\Form\Element\Week',
     'name' => 'week',
     'options' => array(
             'label' => 'Week'
     ),
     'attributes' => array(
             'min' => '2012-W01',
             'max' => '2020-W01',
             'step' => '1', // weeks; default step interval is 1 week
     )
 ));

Note

Note: the min, max, and step attributes should be set prior to calling Zend\Form::prepare(). Otherwise, the default input specification for the element may not contain the correct validation rules.

Public Methods

The following methods are in addition to the inherited methods of Zend\Form\Element\DateTime.

getInputSpecification()

Returns a input filter specification, which includes Zend\Filter\StringTrim and will add the appropriate validators based on the values from the min, max, and step attributes. See getInputSpecification in Zend\Form\Element\DateTime for more information.

One difference from Zend\Form\Element\DateTime is that the Zend\Validator\DateStep validator will expect the step attribute to use an interval of weeks (default is 1 week).

Return type:array