.. include:: /Includes.rst.txt


.. _concepts-validators:

Validators
==========

The form framework ships a set of server-side validators, which implement
Extbase validators. Be aware that not all of the existing validators are
available for each form element, e.g. the "Date range validator" is
only available for the "Date" element. Furthermore, some form elements
(like "Email") already contain reasonable validators.

With the help of the form element property ``validationErrorMessages``
you can define custom validation error messages. The message can also
be set within the form editor.


.. _concepts-validators-client-side-validation:

Client-side validation
----------------------

If a form element is configured accordingly, the form framework adds
HTML 5 based frontend validation. Nevertheless, there is no JavaScript
validation included by default. We as the TYPO3 core have no plans to
opt for a specific solution. This has to be integrated manually.
Reliable and maintained projects are `Parsley <https://github.com/guillaumepotier/Parsley.js>`_
and `jQuery Validation <https://github.com/jquery-validation/jquery-validation>`__.


.. _concepts-validators-localization-client-side-validations:

Localization of client side validations
"""""""""""""""""""""""""""""""""""""""

The displayed validation message is a browser specific text. The output
is not generated by TYPO3 and therefore you cannot change it easily.
Nevertheless, there is a JavaScript solution for changing the validation
message. See `Stack Overflow <http://stackoverflow.com/questions/5272433/html5-form-required-attribute-set-custom-validation-message>`__
for more information.


.. _concepts-validators-server-side-validation:

Server-side validation
----------------------


.. _concepts-validators-alphanumeric:

Alphanumeric validator (:yaml:`Alphanumeric`)
"""""""""""""""""""""""""""""""""""""""""""""

The :ref:`"Alphanumeric validator"<prototypes.prototypeIdentifier.validatorsdefinition.alphanumeric>`
checks for alphanumeric strings. Alphanumeric is defined as a combination of
alphabetic and numeric characters `[A-Z + 0-9]`.


.. _concepts-validators-count:

Number of submitted values validator (:yaml:`Count`)
""""""""""""""""""""""""""""""""""""""""""""""""""""

The :ref:`"Number of submitted values validator"<prototypes.prototypeIdentifier.validatorsdefinition.count>`
checks if the given value contains the specified amount of elements. The
validator has 2 options:

- Minimum [:yaml:`options.minimum`]: The minimum count to accept.
- Maximum [:yaml:`options.maximum`]: The maximum count to accept.


.. _concepts-validators-date_range:

Date range validator (:yaml:`DateRange`)
""""""""""""""""""""""""""""""""""""""""

The :ref:`"Date range validator"<prototypes.prototypeIdentifier.validatorsdefinition.daterange>`
checks if the given value is a valid DateTime object and in-between a specified
date range. The range can be defined by providing a minimum and/or maximum date.
The validator has 2 options:

- Format [:yaml:`options.format`]: The format of the minimum and maximum option.
  Default: [:yaml:`Y-m-d`].
- Minimum date [:yaml:`options.minimum`]: The minimum date formatted as `Y-m-d`.
- Maximum date [:yaml:`options.maximum`]: The maximum date formatted as `Y-m-d`.

The options :yaml:`minimum` and :yaml:`maximum` must have the format 'Y-m-d' which
represents the `RFC 3339 <https://www.w3.org/TR/2011/WD-html-markup-20110405/input.date.html>`__
'full-date' format.

The input must be a DateTime object. This input can be tested against a minimum
date and a maximum date. The minimum date and the maximum date are strings. The minimum
and maximum date can be configured through the validator options.


.. _concepts-validators-date_time:

Date/time validator (:yaml:`DateTime`)
"""""""""""""""""""""""""""""""""""""""

The :ref:`"Date/time validator"<prototypes.prototypeIdentifier.validatorsdefinition.datetime>`
checks if the given value is a valid DateTime object. The date string is
expected to be formatted according to the `W3C standard <http://www.w3.org/TR/NOTE-datetime.html>`__
which is `YYYY-MM-DDT##:##:##+##:##`, for example `2005-08-15T15:52:01+00:00`.


.. _concepts-validators-email:

Email validator (:yaml:`EmailAddress`)
""""""""""""""""""""""""""""""""""""""

The :ref:`"Email validator"<prototypes.prototypeIdentifier.validatorsdefinition.emailaddress>`
checks if the given value is a valid email address. The format of a valid email
address is defined in `RFC 3696 <https://tools.ietf.org/html/rfc3696>`__.
The standard allows international characters and the multiple appearance
of the `@` sign.


.. _concepts-validators-filesize:

File size validator (:yaml:`FileSize`)
""""""""""""""""""""""""""""""""""""""

The :ref:`"File size validator"<prototypes.prototypeIdentifier.validatorsdefinition.filesize>`
validates a file resource regarding its file size. The validator has 2 options:

-   Minimum [:yaml:`options.maximum`]: The minimum filesize to accept. Use the
    format `<size>B|K|M|G`. For example: `10M` means 10 Megabytes.
-   Maximum [:yaml:`options.maximum`]: The maximum filesize to accept. Use the
    format `<size>B|K|M|G`. For example: `10M` means 10 Megabytes.

Use the format `<size>B|K|M|G` when entering file sizes. For example: `10M`
means 10 megabytes. Please keep in mind that the maximum file size also
depends on the :file:`php.ini` settings of your environment.


.. _concepts-validators-floating_point:

Floating-point number validator (:yaml:`Float`)
"""""""""""""""""""""""""""""""""""""""""""""""

The :ref:`"Floating-point number validator"<prototypes.prototypeIdentifier.validatorsdefinition.float>`
checks if the given value is of type float or a string matching the regular
expression `[0-9.e+-]`.


.. _concepts-validators-integer:

Integer number validator (:yaml:`Integer`)
""""""""""""""""""""""""""""""""""""""""""

The :ref:`"Integer number validator"<prototypes.prototypeIdentifier.validatorsdefinition.integer>`
checks if the given value is a valid integer.


.. _concepts-validators-empty:

Empty validator (:yaml:`NotEmpty`)
""""""""""""""""""""""""""""""""""

The :ref:`"Empty validator"<prototypes.prototypeIdentifier.validatorsdefinition.notempty>`
checks if the given value is not empty (NULL, empty string, empty array or empty
object).


.. _concepts-validators-number:

Number validator (:yaml:`Number`)
"""""""""""""""""""""""""""""""""

The :ref:`"Number validator"<prototypes.prototypeIdentifier.validatorsdefinition.number>`
checks if the given value is a number.


.. _concepts-validators-number_range:

Number range validator (:yaml:`NumberRange`)
""""""""""""""""""""""""""""""""""""""""""""

The :ref:`"Number range validator"<prototypes.prototypeIdentifier.validatorsdefinition.numberrange>`
checks if the given value is a number in the specified range. The validator has
2 options:

- Minimum [:yaml:`options.minimum`]: The minimum value to accept.
- Maximum [:yaml:`options.minimum`]: The maximum value to accept.


.. _concepts-validators-regular_expressions:

Regular expression validator (:yaml:`RegularExpression`)
""""""""""""""""""""""""""""""""""""""""""""""""""""""""

The :ref:`"Regular expression validator"<prototypes.prototypeIdentifier.validatorsdefinition.regularexpression>`
checks if the given value matches the specified regular expression. Delimiters
or modifiers are not supported. The validator has 1 option:

- Regular expression [:yaml:`options.regularExpression`]: The regular expression
  to use for validation, used as given.

Imagine the following example. You want the user to provide a domain name. The
submitted value shall only contain the second and the top level domain, e.g.
"typo3.org" instead of "https://typo3.org". The regular expression for this use
case would be :code:`/^[-a-z0-9]+\.[a-z]{2,6}$/`.


.. _concepts-validators-string_length:

String length validator (:yaml:`StringLength`)
""""""""""""""""""""""""""""""""""""""""""""""

The :ref:`"String length validator"<prototypes.prototypeIdentifier.validatorsdefinition.stringlength>`
checks if the given value is a valid string and its length is in the specified
range. The validator has 2 options:

- Minimum [:yaml:`options.minimum`]: The minimum length for a valid string.
- Maximum [:yaml:`options.maximum`]: The maximum length for a valid string.


.. _concepts-validators-text:

Non-XML text validator (:yaml:`Text`)
"""""""""""""""""""""""""""""""""""""

The :ref:`"Non-XML text validator"<prototypes.prototypeIdentifier.validatorsdefinition.text>`
checks if the given value is a valid text (contains no XML tags). This basically
means, that tags are stripped. In this special case quotes are not encoded
(see `filter_var() <https://php.net/filter_var>`__ for more information.

Be aware that the value of this check entirely depends on the output
context. The validated text is not expected to be secure in any circumstance.
If you want to be sure of that, use a customized regular expression or filter on
output.


.. _concepts-validators-validation-message-translation:

Translation of validation messages
----------------------------------

To learn more about this topic, please continue :ref:`here<concepts-frontendrendering-translation-validationerrors>`.


.. _concepts-validators-customvalidatorimplementations:

Custom validator implementations
--------------------------------

Validators belong to a certain ``prototype`` and are defined within the
``validatorsDefinition``. The property ``implementationClassName`` is used
for the validator implementation.

.. code-block:: yaml

   prototypes:
     standard:
       validatorsDefinition:
         Custom:
           implementationClassName: 'VENDOR\MySitePackage\Domain\Validation\CustomValidator'

You can provide options for your validator using the property ``options``.
Those will be used as default values which can be overridden within a
specific ``form definition``.

Define the default value of the option ``yourCustomOption``:

.. code-block:: yaml

   prototypes:
     standard:
       validatorsDefinition:
         Custom:
           implementationClassName: 'VENDOR\MySitePackage\Domain\Validation\CustomValidator'
           options:
             yourCustomOption: 'Jurian'

Override the default value within your ``form definition``:

.. code-block:: yaml

   identifier: sample-form
   label: 'Simple Contact Form'
   prototype: standard
   type: Form

   renderables:
     -
       identifier: subject
       label: 'Name'
       type: Text
       validators:
         -
           identifier: Custom
           options:
             yourCustomOption: 'Mathias'

As mentioned above EXT:form implements Extbase validators. That said,
your own validators should extend :php:`\TYPO3\CMS\Extbase\Validation\Validator\AbstractValidator`.
Read more about this topic in "TYPO3 Explained":
:ref:`t3coreapi:extbase_domain_validator`.
