<commit_before>.. _zend.form.quick-start:

Form Quick Start
================

Forms are relatively easy to create. At the bare minimum, each element or fieldset requires a name; typically,
you'll also provide some attributes to hint to the view layer how it might render the item. The form itself will
also typically compose an ``InputFilter``-- which you can also conveniently create directly in the form via a
factory. Individual elements can hint as to what defaults to use when generating a related input for the input
filter.

Form validation is as easy as providing an array of data to the ``setData()`` method. If you want to simplify your
work even more, you can bind an object to the form; on successful validation, it will be populated from the
validated values.

.. _zend.form.quick-start.programmatic:

.. rubric:: Programmatic Form Creation

If nothing else, you can simply start creating elements, fieldsets, and forms and wiring them together.

.. code-block:: php
   :linenos:

   use Zend\Captcha;
   use Zend\Form\Element;
   use Zend\Form\Fieldset;
   use Zend\Form\Form;
   use Zend\InputFilter\Input;
   use Zend\InputFilter\InputFilter;

   $name = new Element('name');
   $name->setLabel('Your name');
   $name->setAttributes(array(
       'type'  => 'text'
   ));

   $email = new Element('email');
   $email->setLabel('Your email address');
   $email->setAttributes(array(
       'type'  => 'email'
   ));

   $subject = new Element('subject');
   $subject->setLabel('Subject');
   $subject->setAttributes(array(
       'type'  => 'text'
   ));

   $message = new Element('message');
   $message->setLabel('Message');
   $message->setAttributes(array(
       'type'  => 'textarea'
   ));

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

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

   $submit = new Element('send');
   $submit->setLabel('Send');
   $submit->setAttributes(array(
       'type'  => 'submit'
   ));


   $form = new Form('contact');
   $form->add($name);
   $form->add($email);
   $form->add($subject);
   $form->add($message);
   $form->add($captcha);
   $form->add($csrf);
   $form->add($send);

   $nameInput = new Input('name');
   // configure input... and all others
   $inputFilter = new InputFilter();
   // attach all inputs

   $form->setInputFilter($inputFilter);

As a demonstration of fieldsets, let's alter the above slightly. We'll create two fieldsets, one for the sender
information, and another for the message details.

.. code-block:: php
   :linenos:

   $sender = new Fieldset('sender');
   $sender->add($name);
   $sender->add($email);

   $details = new Fieldset('details');
   $details->add($subject);
   $details->add($message);

   $form = new Form('contact');
   $form->add($sender);
   $form->add($details);
   $form->add($captcha);
   $form->add($csrf);
   $form->add($send);

Regardles of approach, as you can see, this can be tedious.

.. _zend.form.quick-start.factory:

.. rubric:: Creation via Factory

You can create the entire form, and input filter, using the ``Factory``. This is particularly nice if you want to
store your forms as pure configuration; you can simply pass the configuration to the factory and be done.

.. code-block:: php
   :linenos:

   use Zend\Form\Factory;
   $factory = new Factory();
   $form    = $factory->createForm(array(
       'hydrator' => 'Zend\Stdlib\Hydrator\ArraySerializable'
       'elements' => array(
           array(
               'name' => 'name',
               'options' => array(
                   'label' => 'Your name',
               ),
               'attributes' => array(
                   'type'  => 'text'
               ),
           ),
           array(
               'name' => 'email',
               'options' => array(
                   'label' => 'Your email address',
               ),
               'attributes' => array(
                   'type'  => 'email',
               ),
           ),
           array(
               'name' => 'subject',
               'options' => array(
                   'label' => 'Subject',
               ),
               'attributes' => array(
                   'type'  => 'text',
               ),
           ),
           array(
               'name' => 'message',
               'options' => array(
                   'label' => 'Message',
               ),
               'attributes' => array(
                   'type'  => 'textarea',
               ),
           ),
           array(
               'type' => 'Zend\Form\Element\Captcha',
               'name' => 'captcha',
               'options' => array(
                   'label' => 'Please verify you are human',
               ),
               'attributes' => array(
                   'captcha' => array(
                       'class' => 'Dumb',
                   ),
               ),
           ),
           array(
               'type' => 'Zend\Form\Element\Csrf',
               'name' => 'security',
           ),
           array(
               'name' => 'send',
               'options' => array(
                   'label' => 'Send',
               ),
               'attributes' => array(
                   'type'  => 'submit',
               ),
           ),
       ),
       /* If we had fieldsets, they'd go here; fieldsets contain
        * "elements" and "fieldsets" keys, and potentially a "type"
        * key indicating the specific FieldsetInterface
        * implementation to use.
       'fieldsets' => array(
       ),
        */

       // Configuration to pass on to
       // Zend\InputFilter\Factory::createInputFilter()
       'input_filter' => array(
           /* ... */
       ),
   ));

If we wanted to use fieldsets, as we demonstrated in the previous example, we could do the following:

.. code-block:: php
   :linenos:

   use Zend\Form\Factory;
   $factory = new Factory();
   $form    = $factory->createForm(array(
       'hydrator'  => 'Zend\Stdlib\Hydrator\ArraySerializable'
       'fieldsets' => array(
           array(<commit_msg>[ZF2-526] Fix example of form factory<commit_after>.. _zend.form.quick-start:

Form Quick Start
================

Forms are relatively easy to create. At the bare minimum, each element or fieldset requires a name; typically,
you'll also provide some attributes to hint to the view layer how it might render the item. The form itself will
also typically compose an ``InputFilter``-- which you can also conveniently create directly in the form via a
factory. Individual elements can hint as to what defaults to use when generating a related input for the input
filter.

Form validation is as easy as providing an array of data to the ``setData()`` method. If you want to simplify your
work even more, you can bind an object to the form; on successful validation, it will be populated from the
validated values.

.. _zend.form.quick-start.programmatic:

.. rubric:: Programmatic Form Creation

If nothing else, you can simply start creating elements, fieldsets, and forms and wiring them together.

.. code-block:: php
   :linenos:

   use Zend\Captcha;
   use Zend\Form\Element;
   use Zend\Form\Fieldset;
   use Zend\Form\Form;
   use Zend\InputFilter\Input;
   use Zend\InputFilter\InputFilter;

   $name = new Element('name');
   $name->setLabel('Your name');
   $name->setAttributes(array(
       'type'  => 'text'
   ));

   $email = new Element('email');
   $email->setLabel('Your email address');
   $email->setAttributes(array(
       'type'  => 'email'
   ));

   $subject = new Element('subject');
   $subject->setLabel('Subject');
   $subject->setAttributes(array(
       'type'  => 'text'
   ));

   $message = new Element('message');
   $message->setLabel('Message');
   $message->setAttributes(array(
       'type'  => 'textarea'
   ));

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

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

   $submit = new Element('send');
   $submit->setLabel('Send');
   $submit->setAttributes(array(
       'type'  => 'submit'
   ));


   $form = new Form('contact');
   $form->add($name);
   $form->add($email);
   $form->add($subject);
   $form->add($message);
   $form->add($captcha);
   $form->add($csrf);
   $form->add($send);

   $nameInput = new Input('name');
   // configure input... and all others
   $inputFilter = new InputFilter();
   // attach all inputs

   $form->setInputFilter($inputFilter);

As a demonstration of fieldsets, let's alter the above slightly. We'll create two fieldsets, one for the sender
information, and another for the message details.

.. code-block:: php
   :linenos:

   $sender = new Fieldset('sender');
   $sender->add($name);
   $sender->add($email);

   $details = new Fieldset('details');
   $details->add($subject);
   $details->add($message);

   $form = new Form('contact');
   $form->add($sender);
   $form->add($details);
   $form->add($captcha);
   $form->add($csrf);
   $form->add($send);

Regardles of approach, as you can see, this can be tedious.

.. _zend.form.quick-start.factory:

.. rubric:: Creation via Factory

You can create the entire form, and input filter, using the ``Factory``. This is particularly nice if you want to
store your forms as pure configuration; you can simply pass the configuration to the factory and be done.

.. code-block:: php
   :linenos:

   use Zend\Form\Factory;
   $factory = new Factory();
   $form    = $factory->createForm(array(
       'hydrator' => 'Zend\Stdlib\Hydrator\ArraySerializable',
       'elements' => array(
           array(
               'spec' => array(
                   'name' => 'name',
                   'options' => array(
                       'label' => 'Your name',
                   ),
                   'attributes' => array(
                       'type'  => 'text'
                   ),
               )
           ),
           array(
               'spec' => array(
                   'name' => 'email',
                   'options' => array(
                       'label' => 'Your email address',
                   ),
                   'attributes' => array(
                       'type'  => 'email',
                   ),
               ),
           ),
           array(
               'spec' => array(
                   'name' => 'subject',
                   'options' => array(
                       'label' => 'Subject',
                   ),
                   'attributes' => array(
                       'type'  => 'text',
                   ),
               ),
           ),
           array(
               'spec' => array(
                   'name' => 'message',
                   'options' => array(
                       'label' => 'Message',
                   ),
                   'attributes' => array(
                       'type'  => 'textarea',
                   ),
               ),
           ),
           array(
               'spec' => array(
                   'type' => 'Zend\Form\Element\Captcha',
                   'name' => 'captcha',
                   'options' => array(
                       'label' => 'Please verify you are human',
                   ),
                   'attributes' => array(
                       'captcha' => array(
                           'class' => 'Dumb',
                       ),
                   ),
               ),
           ),
           array(
               'spec' => array(
                   'type' => 'Zend\Form\Element\Csrf',
                   'name' => 'security',
               ),
           ),
           array(
               'spec' => array(
                   'name' => 'send',
                   'options' => array(
                       'label' => 'Send',
                   ),
                   'attributes' => array(
                       'type'  => 'submit',
                   ),
               ),
           ),
       ),
       /* If we had fieldsets, they'd go here; fieldsets contain
        * "elements" and "fieldsets" keys, and potentially a "type"
        * key indicating the specific FieldsetInterface
        * implementation to use.
       'fieldsets' => array(
       ),
        */

       // Configuration to pass on to
       // Zend\InputFilter\Factory::createInputFilter()
       'input_filter' => array(
           /* ... */
       ),
   ));

If we wanted to use fieldsets, as we demonstrated in the previous example, we could do the following:

.. code-block:: php
   :linenos:

   use Zend\Form\Factory;
   $factory = new Factory();
   $form    = $factory->createForm(array(
       'hydrator'  => 'Zend\Stdlib\Hydrator\ArraySerializable'
       'fieldsets' => array(
           array(
{'fraction_non_alphanumeric': 0.13904077487892516, 'fraction_numerical': 0.0003124511795032026, 'mean_word_length': 1.7862894450489664, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 162, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4147737', 'n_tokens_mistral': 3602, 'n_tokens_neox': 3411, 'n_words': 1018}