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 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.
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 23 24 | 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);
|
Set the name for this element.
Returns Zend\Form\Element
Return the name for this element.
Returns string
Set the label content for this element.
Returns Zend\Form\Element
Return the label content for this element.
Returns string
Set the attributes to use with the label.
Returns Zend\Form\Element
Return the attributes to use with the label.
Returns array
Set options for an element. Accepted options are: "label" and "label_attributes", which call setLabel and setLabelAttributes, respectively.
Returns Zend\Form\Element
Set a single element attribute.
Returns Zend\Form\Element
Retrieve a single element attribute.
Returns mixed
Check if a specific attribute exists for this element.
Returns boolean
Set many attributes at once. Implementation will decide if this will overwrite or merge.
Returns Zend\Form\Element
Retrieve all attributes at once.
Returns array|Traversable
Clear all attributes for this element.
Returns Zend\Form\Element
Set a list of messages to report when validation fails.
Returns Zend\Form\Element
Returns a list of validation failure messages, if any.
Returns array|Traversable
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.
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);
|
The following methods are in addition to the inherited methods of Zend\Form\Element.
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
Return the CAPTCHA adapter for this element.
Returns Zend\Captcha\AdapterInterface
Returns a input filter specification, which includes a Zend\Filter\StringTrim filter, and a CAPTCHA validator.
Returns array
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.
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);
|
The following methods are in addition to the inherited methods of Zend\Form\Element .
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.
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.
Return if a hidden element is generated.
Return type: | boolean |
---|
Set the value to use when the checkbox is checked.
Return the value used when the checkbox is checked.
Return type: | string |
---|
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.
Return the value used when the checkbox is unchecked.
Return type: | string |
---|
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 |
---|
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).
Zend\Form\Element\Collection is meant to be paired with the Zend\Form\View\Helper\FormCollection.
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);
|
The following methods are in addition to the inherited methods of Zend\Form\Element .
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.
Defines how many times the target element will be rendered by the Zend/Form/View/Helper/FormCollection view helper.
Return the number of times the target element will be initially rendered by the Zend/Form/View/Helper/FormCollection view helper.
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.
Return the target element used by the collection.
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.
Return if new elements can by dynamically added in the collection.
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.
Return if a template should be created.
Set the template placeholder (defaults to __index__) used to index element in the template.
Returns the template placeholder used to index element in the template.
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.
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);
|
The following methods are in addition to the inherited methods of Zend\Form\Element.
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\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.
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);
|
The following methods are in addition to the inherited methods of Zend\Form\Element.
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\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.
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);
|
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.
The following methods are in addition to the inherited methods of Zend\Form\Element\DateTime.
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\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.
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);
|
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.
The following methods are in addition to the inherited methods of Zend\Form\Element.
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\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.
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);
|
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.
The following methods are in addition to the inherited methods of Zend\Form\Element\DateTime.
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\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.
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);
|
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.
The following methods are in addition to the inherited methods of Zend\Form\Element.
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 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.
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);
|
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.
The following methods are in addition to the inherited methods of Zend\Form\Element\DateTime.
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 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.
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);
|
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.
The following methods are in addition to the inherited methods of Zend\Form\Element.
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 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.
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);
|
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.
The following methods are in addition to the inherited methods of Zend\Form\Element\Number.
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 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.
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);
|
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.
The following methods are in addition to the inherited methods of Zend\Form\Element\DateTime.
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 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.
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);
|
The following methods are in addition to the inherited methods of Zend\Form\Element.
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 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.
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);
|
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.
The following methods are in addition to the inherited methods of Zend\Form\Element\DateTime.
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
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.