DEPRECATION WARNING

This documentation is not using the current rendering mechanism and is probably outdated. The extension maintainer should switch to the new system. Details on how to use the rendering mechanism can be found here.

Validator¶

Validators are used to check the values of the fields submitted with a form. Their behaviour is almost similar to the base validators from TYPO3, but they do have some more functionality.

To configure the usable validators in the forms configuration, read the chapter “Validators”.

You have the possibility to create your own validators depending on your needs; make sure that they inherit Romm\Formz\Validation\Validator\AbstractValidator, and use correctly the functions from the API.

API¶

The validators of FormZ give you access to the following variables/functions:

$form
$fieldName
$supportedMessages
$supportsAllMessages
$javaScriptValidationFiles
addError($key, $code, array $arguments)
setValidationData($validationData)
setValidationDataValue($key, $value)

Form instance¶

Property

protected $form;

Type

Romm\Formz\Form\FormInterface

Description

You have access with $this->form to the submitted form instance. It allows you for instance to apply some rules depending on the values of other fields.

Warning

$this->form is read-only accessible, you can't edit the fields values.

Field name¶

Property

protected $fieldName;

Type

string

Description

Contains the name of the field currently validated by this validator.

Supported messages list¶

Property

protected $supportedMessages = [];

Type

array

Description

In FormZ, validators use pre-configured messages. Indeed, a validator may return different messages; it should then define in advance what messages can be used: a key for the message, and its configuration.

Use the variable $supportedMessages to define the list of messages used by the validator. You can check the following example to respect the structure:

The values of these messages can be overridden by the fields TypoScript configuration.

protected $supportedMessages = [
   // "default" is the message index.
   'default'    => [
      // "key" is the LLL key of the message.
      'key'        => 'validator.form.contains_values.error',

      // "extension" contains the name of the extension used to
      // fetch the LLL key of the message.
      // If empty, "FormZ" extension is used.
      'extension'    => null
   ],
   'test'    => [
      // If you fill "value", the value will be directly used and
      // the process wont try to fetch a translation.
      'value'        => 'Test message!'
   ]
];

Supports all messages¶

Property

protected $supportsAllMessages = false;

Type

bool

Description

If a validator needs to be able to dynamically add error messages (for instance when using a web service), you can set this value to true. You should set it to false by default, if you are not certain if you need it.

Add an error¶

Function

$this->addError($key, $code, array $arguments);

Return

/

Parameters

$key: the key of the message, must be an index of the array $supportedMessages.
$code: the code of the error, by convention it's the actual timestamp when the developer adds the error.
$arguments: eventual arguments which will be replaced in the text of the message.

Description

You must use this function in order to add an error if the value does not pass the validation.

Save information in an array¶

Function

$this->setValidationData(array $validationData);

Return

/

Parameters

$validationData: arbitrary data array to be saved.

Description

When a validator is used on a form field, you may want to put some arbitrary information aside for a future usage. It is a plain array which can contain any information. This array will then be injected inside the form instance ($this->form) at the end of the validation process.

Save information value in an array¶

Function

$this->setValidationDataValue($key, $value);

Return

/

Parameters

$key: key of the arbitrary data to be saved.
$value: arbitrary data to be saved.

Description

Same as above, but for a simple entry in the array.

Bind a JavaScript file¶

Property

protected static $javaScriptValidationFiles = [];

Type

array

Description

Contains the JavaScript files list which will emulate this validator in the client web browser. Just fill this array, FormZ will import the files automatically.

These files will have to contain the registration declaration of the validator JavaScript version, by using the function Fz.Validation.registerValidator().

Example:

protected static $javaScriptValidationFiles = [
    'EXT:formz/Resources/Public/JavaScript/Validators/Formz.Validator.Required.js'
];

Validator example¶

You can find below a validator example.

<?php
namespace Romm\Formz\Validation\Validator;

use Romm\Formz\Validation\Validator\AbstractValidator;

class ContainsValuesValidator extends AbstractValidator {
    /**
     * @inheritdoc
     */
    protected $supportedOptions = [
       'values' => [
          [],
          'The values that are accepted',
          'array',
          true
       ]
    ];

    /**
     * @inheritdoc
     */
    protected $supportedMessages = [
       'default'    => [
          'key'        => 'validator.form.contains_values.error',
          'extension'    => null
       ]
    ];

    /**
     * @inheritdoc
     */
    public function isValid($valuesArray)
    {
       $flag = false;

       if (is_array($valuesArray)) {
          foreach ($valuesArray as $value) {
             if (in_array($value, $this->options['values'])) {
                $flag = true;
                break;
             }
          }
       }

       if (false === $flag) {
          $this->addError(
             'default'
             1445952458,
             [implode(
               ', ',
               $this->options['values']
            )]
          );
       }
    }
}