Zend\Form\Element

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.

Zend\Form\Element

Zend\Form\Element is a base class for all specialized elements and Zend\Form\Fieldset, but can also be used for all generic text, select, radio, etc. type form inputs which do not have a specialized element available.

Basic Usage of Zend\Form\Element

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('username');
$username
    ->setLabel('Username');
    ->setAttributes(array(
        'type'  => 'text',
        'class' => 'username',
        'size'  => '30',
    ));

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

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

Available Methods

setName

setName(string $name)

Set the name for this element.

Returns Zend\Form\Element

getName

getName()

Return the name for this element.

Returns string

setLabel

setLabel(string $label)

Set the label content for this element.

Returns Zend\Form\Element

getLabel

getLabel()

Return the label content for this element.

Returns string

setLabelAttributes

setLabelAttributes(array $labelAttributes)

Set the attributes to use with the label.

Returns Zend\Form\Element

getLabelAttributes

getLabelAttributes()

Return the attributes to use with the label.

Returns array

setOptions

setOptions(array $options)

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

Returns Zend\Form\Element

setAttribute

setAttribute(string $key, mixed $value)

Set a single element attribute.

Returns Zend\Form\Element

getAttribute

getAttribute(string $key)

Retrieve a single element attribute.

Returns mixed

hasAttribute

hasAttribute(string $key)

Check if a specific attribute exists for this element.

Returns boolean

setAttributes

setAttributes(array|Traversable $arrayOrTraversable)

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

Returns Zend\Form\Element

getAttributes

getAttributes()

Retrieve all attributes at once.

Returns array|Traversable

clearAttributes

clearAttributes()

Clear all attributes for this element.

Returns Zend\Form\Element

setMessages

setMessages(array|Traversable $messages)

Set a list of messages to report when validation fails.

Returns Zend\Form\Element

setMessages

getMessages()

Returns a list of validation failure messages, if any.

Returns array|Traversable

Zend\Form\Element\Captcha

The Captcha element 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 of Zend\Form\Element\Captcha

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);

Available Methods

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

setCaptcha

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.

Returns Zend\Form\Element\Captcha

getCaptcha

getCaptcha()

Return the CAPTCHA adapter for this element.

Returns Zend\Captcha\AdapterInterface

getInputSpecification

getInputSpecification()

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

Returns array

Zend\Form\Element\Checkbox

The Checkbox element 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 of Zend\Form\Element\Checkbox

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);

Available Methods

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

setOptions

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

setUseHiddenElement($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

useHiddenElement()

Return if a hidden element is generated.

setCheckedValue

setCheckedValue($checkedValue)

Set the value to use when the checkbox is checked.

getCheckedValue

getCheckedValue()

Return the value used when the checkbox is checked.

setUncheckedValue

setUncheckedValue($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

getUncheckedValue()

Return the value used when the checkbox is unchecked.

getInputSpecification

getInputSpecification()

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

Returns array

Zend\Form\Element\Csrf

The Csrf element 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 of Zend\Form\Element\Csrf

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);

Available Methods

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

getInputSpecification

getInputSpecification()

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

Returns array

Zend\Form\Element\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).

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

Basic Usage of Zend\Form\Element\Collection

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);

Available Methods

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

setOptions

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", "should_create_template" and "template_placeholder" , which call setTargetElement, setCount, setAllowAdd, setShouldCreateTemplate and setTemplatePlaceholder , respectively.

setCount

setCount($count)

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

getCount

getCount()

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

setTargetElement

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

getTargetElement()

Return the target element used by the collection.

setAllowAdd

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.

getAllowAdd

getAllowAdd()

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

setShouldCreateTemplate

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

getAllowAdd()

Return if a template should be created.

setTemplatePlaceholder

setTemplatePlaceholder($templatePlaceholder)

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

getTemplatePlaceholder

getTemplatePlaceholder()

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

Zend\Form\Element\Color

The Color element 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 of Zend\Form\Element\Color

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);

Available Methods

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

getInputSpecification

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.

Returns array

Zend\Form\Element\DateTimeLocal

The DateTimeLocal element 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 of Zend\Form\Element\DateTimeLocal

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
    ));

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

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.

Available Methods

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

getInputSpecification

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.

Returns array

Zend\Form\Element\DateTime

The DateTime element 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 of Zend\Form\Element\DateTime

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
    ));

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

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.

Available Methods

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

getInputSpecification

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

Returns array

Zend\Form\Element\Date

The Date element 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 of Zend\Form\Element\Date

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
    ));

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

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.

Available Methods

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

getInputSpecification

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

Returns array

Zend\Form\Element\Email

The Email element 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 of Zend\Form\Element\Email

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);

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.

Available Methods

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

getInputSpecification

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.

Returns array

Zend\Form\Element\Month

The Month element 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 of Zend\Form\Element\Month

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);

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.

Available Methods

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

getInputSpecification

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

Returns array

Zend\Form\Element\Number

The Number element 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 of Zend\Form\Element\Number

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);

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.

Available Methods

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

getInputSpecification

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.

Returns array

Zend\Form\Element\Range

The Range element 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 of Zend\Form\Element\Range

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);

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.

Available Methods

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

getInputSpecification

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.

Returns array

Zend\Form\Element\Time

The Time element 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 of Zend\Form\Element\Time

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

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);

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.

Available Methods

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

getInputSpecification

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

Returns array

Zend\Form\Element\Url

The Url element 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 of Zend\Form\Element\Url

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);

Available Methods

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

getInputSpecification

getInputSpecification()

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

Returns array

Zend\Form\Element\Week

The Week element 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 of Zend\Form\Element\Week

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);

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.

Available Methods

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

getInputSpecification

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

Returns array