Validation Component

    Phalcon\Validation is an independent validation component that validates an arbitrary set of data. This component can be used to implement validation rules on data objects that do not belong to a model or collection.

    The following example shows its basic usage:

    The loosely-coupled design of this component allows you to create your own validators along with the ones provided by the framework.

    Initializing Validation

    Validation chains can be initialized in a direct manner by just adding validators to the Phalcon\Validation object. You can put your validations in a separate file for better re-use code and organization:

    3. use Phalcon\Validation;
    4. use Phalcon\Validation\Validator\Email;
    5. use Phalcon\Validation\Validator\PresenceOf;
    7. class MyValidation extends Validation
    8. {
    9.     public function initialize()
    10.     {
    11.         $this->add(
    12.             'name',
    13.             new PresenceOf(
    14.                 [
    15.                     'message' => 'The name is required',
    16.                 ]
    17.             )
    18.         );
    20.         $this->add(
    21.             'email',
    22.             new PresenceOf(
    23.                 [
    24.                     'message' => 'The e-mail is required',
    25.                 ]
    26.             )
    27.         );
    29.         $this->add(
    30.             'email',
    31.             new Email(
    32.                 [
    33.                     'message' => 'The e-mail is not valid',
    34.                 ]
    35.             )
    36.         );
    37.     }
    38. }

    Then initialize and use your own validator:

    1. <?php
    3. $validation = new MyValidation();
    5. $messages = $validation->validate($_POST);
    7. if (count($messages)) {
    8.     foreach ($messages as $message) {
    9.         echo $message, '<br>';
    10.     }
    11. }

    Validators

    Phalcon exposes a set of built-in validators for this component:

    1. <?php
    3. use Phalcon\Validation;
    4. use Phalcon\Validation\Message;
    5. use Phalcon\Validation\Validator;
    7. class IpValidator extends Validator
    8. {
    9.     /**
    10.      * Executes the validation
    11.      *
    12.      * @param Validation $validator
    13.      * @param string     $attribute
    14.      * @return boolean
    15.      */
    16.     public function validate(Validation $validator, $attribute)
    17.     {
    18.         $value = $validator->getValue($attribute);
    20.         if (!filter_var($value, FILTER_VALIDATE_IP, FILTER_FLAG_IPV4 | FILTER_FLAG_IPV6)) {
    21.             $message = $this->getOption('message');
    23.             if (!$message) {
    24.                 $message = 'The IP is not valid';
    25.             }
    27.             $validator->appendMessage(
    28.                 new Message($message, $attribute, 'Ip')
    30.             return false;
    31.         }
    33.         return true;
    34.     }
    35. }

    It is important that validators return a valid boolean value indicating if the validation was successful or not.

    By using Phalcon\Validation\Validator\Callback you can execute custom function which must return boolean or new validator class which will be used to validate the same field. By returning true validation will be successful, returning false will mean validation failed. When executing this validator Phalcon will pass data depending what it is - if it’s an entity (i.e. a model, a stdClass etc.) then entity will be passed, otherwise data (i.e an array like $_POST). There is example:

    Validation Messages

    Phalcon\Validation has a messaging subsystem that provides a flexible way to output or store the validation messages generated during the validation processes.

    Each message consists of an instance of the class . The set of messages generated can be retrieved with the getMessages() method. Each message provides extended information like the attribute that generated the message or the message type:

    3. $messages = $validation->validate();
    5. if (count($messages)) {
    6.     foreach ($messages as $message) {
    7.         echo 'Message: ', $message->getMessage(), "\n";
    8.         echo 'Field: ', $message->getField(), "\n";
    9.         echo 'Type: ', $message->getType(), "\n";
    10.     }
    11. }

    You can pass a message parameter to change/translate the default message in each validator, even it’s possible to use the wildcard :field in the message to be replaced by the label of the field:

    1. <?php
    3. use Phalcon\Validation\Validator\Email;
    5. $validation->add(
    6.     'email',
    7.     new Email(
    8.         [
    9.             'message' => 'The e-mail is not valid',
    10.         ]
    11.     )
    12. );

    By default, the getMessages() method returns all the messages generated during validation. You can filter messages for a specific field using the filter() method:

    1. <?php
    3. $messages = $validation->validate();
    5. if (count($messages)) {
    6.     // Filter only the messages generated for the field 'name'
    7.     $filteredMessages = $messages->filter('name');
    9.     foreach ($filteredMessages as $message) {
    10.         echo $message;
    11.     }
    12. }

    Filtering of Data

    Filtering and sanitizing is performed using the component. You can add more filters to this component or use the built-in ones.

    When validations are organized in classes, you can implement the beforeValidation() and afterValidation() methods to perform additional checks, filters, clean-up, etc. If the beforeValidation() method returns false the validation is automatically cancelled:

    1. <?php
    3. use Phalcon\Validation;
    5. class LoginValidation extends Validation
    6. {
    7.     public function initialize()
    8.     {
    9.         // ...
    10.     }
    12.     /**
    13.      * Executed before validation
    14.      *
    15.      * @param array $data
    16.      * @param object $entity
    17.      * @param Phalcon\Validation\Message\Group $messages
    18.      * @return bool
    19.      */
    20.     public function beforeValidation($data, $entity, $messages)
    21.     {
    22.         if ($this->request->getHttpHost() !== 'admin.mydomain.com') {
    23.             $messages->appendMessage(
    24.                 new Message('Only users can log on in the administration domain')
    25.             );
    27.             return false;
    28.         }
    30.         return true;
    31.     }
    33.     /**
    34.      * Executed after validation
    35.      *
    36.      * @param array $data
    37.      * @param object $entity
    38.      * @param Phalcon\Validation\Message\Group $messages
    39.      */
    40.     public function afterValidation($data, $entity, $messages)
    41.     {
    42.         // ... Add additional messages or perform more validations
    43.     }
    44. }

    Cancelling Validations

    By default all validators assigned to a field are tested regardless if one of them have failed or not. You can change this behavior by telling the validation component which validator may stop the validation:

    1. <?php
    2. use Phalcon\Validation;
    3. use Phalcon\Validation\Validator\Regex;
    6. $validation = new Validation();
    8. $validation->add(
    9.     'telephone',
    10.     new PresenceOf(
    11.         [
    12.             'message'      => 'The telephone is required',
    13.             'cancelOnFail' => true,
    14.         ]
    15.     )
    16. );
    18. $validation->add(
    19.     'telephone',
    20.     new Regex(
    21.         [
    22.             'message' => 'The telephone is required',
    23.             'pattern' => '/\+44 [0-9]+/',
    24.         ]
    25.     )
    26. );
    28. $validation->add(
    29.     'telephone',
    30.     new StringLength(
    31.         [
    32.             'messageMinimum' => 'The telephone is too short',
    33.             'min'            => 2,
    34.         ]
    35.     )
    36. );

    The first validator has the option cancelOnFail with a value of true, therefore if that validator fails the remaining validators in the chain are not executed.

    If you are creating custom validators you can dynamically stop the validation chain by setting the cancelOnFail option:

    1. <?php
    3. use Phalcon\Validation;
    4. use Phalcon\Validation\Message;
    5. use Phalcon\Validation\Validator;
    7. class MyValidator extends Validator
    8. {
    9.     /**
    10.      * Executes the validation
    11.      *
    12.      * @param Phalcon\Validation $validator
    13.      * @param string $attribute
    14.      * @return boolean
    15.      */
    16.     public function validate(Validation $validator, $attribute)
    17.     {
    18.         // If the attribute value is name we must stop the chain
    19.         if ($attribute === 'name') {
    20.             $validator->setOption('cancelOnFail', true);
    21.         }
    23.         // ...
    24.     }
    25. }

    Avoid validating empty values

    You can pass the option allowEmpty to all the built-in validators to avoid the validation to be performed if an empty value is passed:

    1. <?php
    3. use Phalcon\Validation;
    5. class CompanyValidation extends Validation
    6. {
    7.     /**
    8.      * @var PhoneValidation
    9.      */
    10.     protected $phoneValidation;
    12.     public function initialize()
    13.     {
    14.         $this->phoneValidation = new PhoneValidation();
    15.     }
    17.     public function afterValidation($data, $entity, $messages)
    18.     {
    19.         $phoneValidationMessages = $this->phoneValidation->validate(
    20.             $data['phone']
    21.         );
    23.         $messages->appendMessages(
    24.             $phoneValidationMessages
    25.         );
    27. }