Validation

Validation is a very common task in web applications. Data entered in formsneeds to be validated. Data also needs to be validated before it is writteninto a database or passed to a web service.

Symfony provides a Validator component that makes this task easy andtransparent. This component is based on the JSR303 Bean Validation specification.

Installation

In applications using Symfony Flex, run this command toinstall the validator before using it:

$ composer require symfony/validator doctrine/annotations

The Basics of Validation

The best way to understand validation is to see it in action. To start, supposeyou've created a plain-old-PHP object that you need to use somewhere inyour application:

// src/Entity/Author.php
namespace App\Entity;
 
class Author
{
    private $name;
}

So far, this is just an ordinary class that serves some purpose inside yourapplication. The goal of validation is to tell you if the dataof an object is valid. For this to work, you'll configure a list of rules(called constraints) that the object mustfollow in order to be valid. These rules are usually defined using PHP code orannotations but they can also be defined as .yaml or.xml files inside the config/validator/ directory:

For example, to guarantee that the $name property is not empty, add thefollowing:

• Annotations

// src/Entity/Author.php
namespace App\Entity;
 
// ...
use Symfony\Component\Validator\Constraints as Assert;
 
class Author
{
    /**
     * @Assert\NotBlank
     */
    private $name;
}

• YAML

# config/validator/validation.yaml
App\Entity\Author:
    properties:
        name:
            - NotBlank: ~

• XML

<!-- config/validator/validation.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping
        https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
 
    <class name="App\Entity\Author">
        <property name="name">
            <constraint name="NotBlank"/>
        </property>
    </class>
</constraint-mapping>

• PHP

// src/Entity/Author.php
namespace App\Entity;
// ...
use Symfony\Component\Validator\Constraints\NotBlank;
use Symfony\Component\Validator\Mapping\ClassMetadata;
 
class Author
{
    private $name;
 
    public static function loadValidatorMetadata(ClassMetadata $metadata)
    {
        $metadata->addPropertyConstraint('name', new NotBlank());
    }
}

Tip

Symfony's validator uses PHP reflection, as well as "getter" methods, toget the value of any property, so they can be public, private or protected(see Constraint Targets).

Using the validator Service

Next, to actually validate an Author object, use the validate() methodon the validator service (which implements ValidatorInterface).The job of the validator is to read the constraints (i.e. rules)of a class and verify if the data on the object satisfies thoseconstraints. If validation fails, a non-empty list of errors(class ConstraintViolationList) isreturned. Take this simple example from inside a controller:

// ...
use App\Entity\Author;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Validator\Validator\ValidatorInterface;
 
// ...
public function author(ValidatorInterface $validator)
{
    $author = new Author();
 
    // ... do something to the $author object
 
    $errors = $validator->validate($author);
 
    if (count($errors) > 0) {
        /*
         * Uses a __toString method on the $errors variable which is a
         * ConstraintViolationList object. This gives us a nice string
         * for debugging.
         */
        $errorsString = (string) $errors;
 
        return new Response($errorsString);
    }
 
    return new Response('The author is valid! Yes!');
}

If the $name property is empty, you will see the following errormessage:

Object(App\Entity\Author).name:
    This value should not be blank

If you insert a value into the name property, the happy success messagewill appear.

Tip

Most of the time, you won't interact directly with the validatorservice or need to worry about printing out the errors. Most of the time,you'll use validation indirectly when handling submitted form data. Formore information, see how to validate Symfony forms.

You could also pass the collection of errors into a template:

if (count($errors) > 0) {
    return $this->render('author/validation.html.twig', [
        'errors' => $errors,
    ]);
}

Inside the template, you can output the list of errors exactly as needed:

{# templates/author/validation.html.twig #}
<h3>The author has the following errors</h3>
<ul>
{% for error in errors %}
    <li>{{ error.message }}</li>
{% endfor %}
</ul>

Note

Each validation error (called a "constraint violation"), is represented bya ConstraintViolation object.

Configuration

Before using the Symfony validator, make sure it's enabled in the main configfile:

• YAML

# config/packages/framework.yaml
framework:
    validation: { enabled: true }

• XML

<!-- config/packages/framework.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:framework="http://symfony.com/schema/dic/symfony"
    xsi:schemaLocation="http://symfony.com/schema/dic/services
        https://symfony.com/schema/dic/services/services-1.0.xsd
        http://symfony.com/schema/dic/symfony https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
 
    <framework:config>
        <framework:validation enabled="true"/>
    </framework:config>
</container>

• PHP

// config/packages/framework.php
$container->loadFromExtension('framework', [
    'validation' => [
        'enabled' => true,
    ],
]);

Besides, if you plan to use annotations to configure validation, replace theprevious configuration by the following:

• YAML

# config/packages/framework.yaml
framework:
    validation: { enable_annotations: true }

• XML

<!-- config/packages/framework.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:framework="http://symfony.com/schema/dic/symfony"
    xsi:schemaLocation="http://symfony.com/schema/dic/services
        https://symfony.com/schema/dic/services/services-1.0.xsd
        http://symfony.com/schema/dic/symfony https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
 
    <framework:config>
        <framework:validation enable-annotations="true"/>
    </framework:config>
</container>

• PHP

// config/packages/framework.php
$container->loadFromExtension('framework', [
    'validation' => [
        'enable_annotations' => true,
    ],
]);

Tip

When using PHP, YAML, and XML files instead of annotations, Symfony looksfor by default in the config/validator/ directory, but you can configureother directories with the validation.mapping.paths option.

Constraints

The validator is designed to validate objects against constraints (i.e.rules). In order to validate an object, simply map one or more constraintsto its class and then pass it to the validator service.

Behind the scenes, a constraint is simply a PHP object that makes an assertivestatement. In real life, a constraint could be: 'The cake must not be burned'.In Symfony, constraints are similar: they are assertions that a conditionis true. Given a value, a constraint will tell you if that valueadheres to the rules of the constraint.

Supported Constraints

Symfony packages many of the most commonly-needed constraints:

Basic Constraints

These are the basic constraints: use them to assert very basic things aboutthe value of properties or the return value of methods on your object.

• NotBlank
• Blank
• NotNull
• IsNull
• IsTrue
• IsFalse
• Type

String Constraints

• Email
• Length
• Url
• Regex
• Ip
• Json
• Uuid
• UserPassword
• NotCompromisedPassword

Comparison Constraints

• EqualTo
• NotEqualTo
• IdenticalTo
• NotIdenticalTo
• LessThan
• LessThanOrEqual
• GreaterThan
• GreaterThanOrEqual
• Range
• DivisibleBy
• Unique

Number Constraints

• Positive
• PositiveOrZero
• Negative
• NegativeOrZero

Date Constraints

• Date
• DateTime
• Time
• Timezone

Choice Constraints

• Choice
• Language
• Locale
• Country

File Constraints

• File
• Image

Financial and other Number Constraints

• Bic
• CardScheme
• Currency
• Luhn
• Iban
• Isbn
• Issn

Other Constraints

• Callback
• Expression
• All
• Valid
• Traverse
• Collection
• Count
• UniqueEntityYou can also create your own custom constraints. This topic is covered inthe How to Create a custom Validation Constraint article.

Constraint Configuration

Some constraints, like NotBlank,are simple whereas others, like the Choiceconstraint, have several configuration options available. Suppose that theAuthor class has another property called genre that defines theliterature genre mostly associated with the author, which can be set to either"fiction" or "non-fiction":

• Annotations

// src/Entity/Author.php
namespace App\Entity;
 
// ...
use Symfony\Component\Validator\Constraints as Assert;
 
class Author
{
    /**
     * @Assert\Choice(
     *     choices = { "fiction", "non-fiction" },
     *     message = "Choose a valid genre."
     * )
     */
    private $genre;
 
    // ...
}

• YAML

# config/validator/validation.yaml
App\Entity\Author:
    properties:
        genre:
            - Choice: { choices: [fiction, non-fiction], message: Choose a valid genre. }
        # ...

• XML

<!-- config/validator/validation.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping
        https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
 
    <class name="App\Entity\Author">
        <property name="genre">
            <constraint name="Choice">
                <option name="choices">
                    <value>fiction</value>
                    <value>non-fiction</value>
                </option>
                <option name="message">Choose a valid genre.</option>
            </constraint>
        </property>
 
        <!-- ... -->
    </class>
</constraint-mapping>

• PHP

// src/Entity/Author.php
namespace App\Entity;
 
// ...
use Symfony\Component\Validator\Constraints as Assert;
use Symfony\Component\Validator\Mapping\ClassMetadata;
 
class Author
{
    private $genre;
 
    // ...
 
    public static function loadValidatorMetadata(ClassMetadata $metadata)
    {
        // ...
 
        $metadata->addPropertyConstraint('genre', new Assert\Choice([
            'choices' => ['fiction', 'non-fiction'],
            'message' => 'Choose a valid genre.',
        ]));
    }
}

The options of a constraint can always be passed in as an array. Some constraints,however, also allow you to pass the value of one, "default", option in placeof the array. In the case of the Choice constraint, the choicesoptions can be specified in this way.

• Annotations

// src/Entity/Author.php
namespace App\Entity;
 
// ...
use Symfony\Component\Validator\Constraints as Assert;
 
class Author
{
    /**
     * @Assert\Choice({"fiction", "non-fiction"})
     */
    private $genre;
 
    // ...
}

• YAML

# config/validator/validation.yaml
App\Entity\Author:
    properties:
        genre:
            - Choice: [fiction, non-fiction]
        # ...

• XML

<!-- config/validator/validation.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping
        https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
 
    <class name="App\Entity\Author">
        <property name="genre">
            <constraint name="Choice">
                <value>fiction</value>
                <value>non-fiction</value>
            </constraint>
        </property>
 
        <!-- ... -->
    </class>
</constraint-mapping>

• PHP

// src/Entity/Author.php
namespace App\Entity;
 
// ...
use Symfony\Component\Validator\Constraints as Assert;
use Symfony\Component\Validator\Mapping\ClassMetadata;
 
class Author
{
    private $genre;
 
    public static function loadValidatorMetadata(ClassMetadata $metadata)
    {
        // ...
 
        $metadata->addPropertyConstraint(
            'genre',
            new Assert\Choice(['fiction', 'non-fiction'])
        );
    }
}

This is purely meant to make the configuration of the most common option ofa constraint shorter and quicker.

If you're ever unsure of how to specify an option, either check the namespaceSymfony\Component\Validator\Constraints for the constraint or play it safeby always passing in an array of options (the first method shown above).

Constraints in Form Classes

Constraints can be defined while building the form via the constraints optionof the form fields:

public function buildForm(FormBuilderInterface $builder, array $options)
{
    $builder
        ->add('myField', TextType::class, [
            'required' => true,
            'constraints' => [new Length(['min' => 3])]
        ])
    ;
}

Constraint Targets

Constraints can be applied to a class property (e.g. name), a publicgetter method (e.g. getFullName()) or an entire class. Property constraintsare the most common and easy to use. Getter constraints allow you to specifymore complex validation rules. Finally, class constraints are intendedfor scenarios where you want to validate a class as a whole.

Properties

Validating class properties is the most basic validation technique. Symfonyallows you to validate private, protected or public properties. The nextlisting shows you how to configure the $firstName property of an Authorclass to have at least 3 characters.

• Annotations

// src/Entity/Author.php
 
// ...
use Symfony\Component\Validator\Constraints as Assert;
 
class Author
{
    /**
     * @Assert\NotBlank
     * @Assert\Length(min=3)
     */
    private $firstName;
}

• YAML

# config/validator/validation.yaml
App\Entity\Author:
    properties:
        firstName:
            - NotBlank: ~
            - Length:
                min: 3

• XML

<!-- config/validator/validation.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping
        https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
 
    <class name="App\Entity\Author">
        <property name="firstName">
            <constraint name="NotBlank"/>
            <constraint name="Length">
                <option name="min">3</option>
            </constraint>
        </property>
    </class>
</constraint-mapping>

• PHP

// src/Entity/Author.php
namespace App\Entity;
 
// ...
use Symfony\Component\Validator\Constraints as Assert;
use Symfony\Component\Validator\Mapping\ClassMetadata;
 
class Author
{
    private $firstName;
 
    public static function loadValidatorMetadata(ClassMetadata $metadata)
    {
        $metadata->addPropertyConstraint('firstName', new Assert\NotBlank());
        $metadata->addPropertyConstraint(
            'firstName',
            new Assert\Length(["min" => 3])
        );
    }
}

Getters

Constraints can also be applied to the return value of a method. Symfonyallows you to add a constraint to any public method whose name starts with"get", "is" or "has". In this guide, these types of methods are referred toas "getters".

The benefit of this technique is that it allows you to validate your objectdynamically. For example, suppose you want to make sure that a password fielddoesn't match the first name of the user (for security reasons). You cando this by creating an isPasswordSafe() method, and then asserting thatthis method must return true:

• Annotations

// src/Entity/Author.php
namespace App\Entity;
 
// ...
use Symfony\Component\Validator\Constraints as Assert;
 
class Author
{
    /**
     * @Assert\IsTrue(message="The password cannot match your first name")
     */
    public function isPasswordSafe()
    {
        // ... return true or false
    }
}

• YAML

# config/validator/validation.yaml
App\Entity\Author:
    getters:
        passwordSafe:
            - 'IsTrue': { message: 'The password cannot match your first name' }

• XML

<!-- config/validator/validation.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping
        https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
 
    <class name="App\Entity\Author">
        <getter property="passwordSafe">
            <constraint name="IsTrue">
                <option name="message">The password cannot match your first name</option>
            </constraint>
        </getter>
    </class>
</constraint-mapping>

• PHP

// src/Entity/Author.php
namespace App\Entity;
 
// ...
use Symfony\Component\Validator\Constraints as Assert;
use Symfony\Component\Validator\Mapping\ClassMetadata;
 
class Author
{
    public static function loadValidatorMetadata(ClassMetadata $metadata)
    {
        $metadata->addGetterConstraint('passwordSafe', new Assert\IsTrue([
            'message' => 'The password cannot match your first name',
        ]));
    }
}

Now, create the isPasswordSafe() method and include the logic you need:

public function isPasswordSafe()
{
    return $this->firstName !== $this->password;
}

Note

The keen-eyed among you will have noticed that the prefix of the getter("get", "is" or "has") is omitted in the mappings for the YAML, XML and PHPformats. This allows you to move the constraint to a property with the samename later (or vice versa) without changing your validation logic.

Classes

Some constraints apply to the entire class being validated. For example,the Callback constraint is a genericconstraint that's applied to the class itself. When that class is validated,methods specified by that constraint are simply executed so that each canprovide more custom validation.

Final Thoughts

The Symfony validator is a powerful tool that can be leveraged toguarantee that the data of any object is "valid". The power behind validationlies in "constraints", which are rules that you can apply to properties orgetter methods of your object. And while you'll most commonly use the validationframework indirectly when using forms, remember that it can be used anywhereto validate any object.

Learn more

• How to Create a custom Validation Constraint
• How to Apply only a Subset of all Your Validation Constraints (Validation Groups)
• How to Validate Raw Values (Scalar Values and Arrays)
• How to Sequentially Apply Validation Groups
• How to Handle Different Error Levels
• How to Translate Validation Constraint Messages