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.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
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.

setAttribute(string $key, mixed $value)

Set a single element attribute.

getAttribute(string $key)

Retrieve a single element attribute.

Return type:mixed
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
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.

1
2
3
4
5
6
7
8
9
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 pairs 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.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
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:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
     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".

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
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:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
 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 <zend.form.element.methods.set-options>` , 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

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 does not know in advance how many elements you need (in the case of elements dynamically added to a form using JavaScript, for instance). For more information about Collection, please refer to ZendCollection tutorial.

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

Basic Usage

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
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:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
 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 <zend.form.element.methods.set-options>` , 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.

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

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".

1
2
3
4
5
6
7
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:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
 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(CsrfValidator $validator)

Override the default CSRF validator by setting another one.

getCsrfValidator()

Get the CSRF validator.

Return type:CsrfValidator

File

Zend\Form\Element\File represents a form file input. It can be used with the Zend\Form\View\Helper\FormFile view helper.

Zend\Form\Element\File extends from ZendFormElement.

Basic Usage

This element automatically adds a "type" attribute of value "file", and will set the form’s enctype to multipart/form-data.

1
2
3
4
5
6
7
use Zend\Form\Element;
use Zend\Form\Form;

$file = new Element\File('my-file');

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

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 ZendFormElement.

Basic Usage

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

1
2
3
4
5
6
7
8
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:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
 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 ZendFormElement.

Basic Usage

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

1
2
3
4
5
6
7
8
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);

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.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
     use Zend\Form\Element;
     use Zend\Form\Form;

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

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

Using the array notation:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
 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 <zend.form.element.checkbox.methods.set-options>` , 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 ZendFormElement.

Basic Usage

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

1
2
3
4
5
6
7
8
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.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
     use Zend\Form\Element;
     use Zend\Form\Form;

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

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

Using the array notation:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
 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".

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
     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:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
 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:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
 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.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
     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 <zend.form.element.checkbox.methods.set-options>` , are: "value_options" and "empty_option", which call setValueOptions and setEmptyOption, respectively.

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
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.

setEmptyOption()

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

Return type:string

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 ZendFormElement.

Basic Usage

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

1
2
3
4
5
6
7
8
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 ZendFormElement.

Basic Usage

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

1
2
3
4
5
6
7
8
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 ZendFormElement.

Basic Usage

1
2
3
4
5
6
7
8
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\FormColo type color`_. This element adds filters and a ``Regex validator to it’s input filter spr`` for `HTML5 inputs withecification 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".

1
2
3
4
5
6
7
8
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:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
 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".

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
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
    ));

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

Here is with the array notation:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
 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'
     ),
     '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. 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".

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
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
    ));

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

Here is with the array notation:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
 use Zend\Form\Form;

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

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 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 a Zend\Validator\DateStep validator will be added to ensure the date value is within a certain interval of minutes (default is 1 minute).

Return type:array

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".

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
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
    ));

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

Here is with the array notation:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
 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'
     ),
     '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. 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".

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
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:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
 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

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".

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
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:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
 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".

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
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:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
 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\LessThanValidator 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 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".

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
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:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
 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".

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
use Zend\Form\Element;
use Zend\Form\Form;

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

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

Here is the same example using the array notation:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
 use Zend\Form\Form;

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

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 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".

1
2
3
4
5
6
7
8
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:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
 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".

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
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:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
 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
Edit this document

Edit this document

The source code of this file is hosted on GitHub. Everyone can update and fix errors in this document with few clicks - no downloads needed.

  1. Login with your GitHub account.
  2. Go to Form Elements on GitHub.
  3. Edit file contents using GitHub's text editor in your web browser
  4. Fill in the Commit message text box at the end of the page telling why you did the changes. Press Propose file change button next to it when done.
  5. On Send a pull request page you don't need to fill in text anymore. Just press Send pull request button.
  6. Your changes are now queued for review under project's Pull requests tab on GitHub.