Callback

The purpose of the Callback constraint is to create completely custom validation rules using your own PHP code. You can define one or more callbacks as closures directly in the properties to validate, or as methods of the class (or external callables) that add the validation errors themselves.

Applies to	class or property/method
Class	Callback
Validator	CallbackValidator

Callbacks in Properties

The simplest way to use this constraint is to define the callback as a closure in the attribute of the property to validate (closures can't be defined in YAML or XML configuration). The closure receives the value of the property and must return true or false. When it returns false, Symfony adds a violation to that property with the text of the message option:

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
        // src/Entity/Order.php
namespace App\Entity;

use Symfony\Component\Validator\Constraints as Assert;

class Order
{
    #[Assert\Callback(
        static function (\DateTimeImmutable $value) {
            return $value > new \DateTimeImmutable('today');
        },
        message: 'The delivery date must be in the future.',
    )]
    public \DateTimeImmutable $deliveryDate;

    // ...
}
    

8.2

The message option was introduced in Symfony 8.2.

Note

Defining closures inside attributes requires PHP 8.5 or higher. In earlier PHP versions, define the callback as a public static method of the class and reference it with an array callable:

        1
2
3
4
5
        #[Assert\Callback(
    [self::class, 'isFutureDate'],
    message: 'The delivery date must be in the future.',
)]
public \DateTimeImmutable $deliveryDate;
    

If the validation rule involves other properties, the closure can get the object being validated from the execution context, which is passed as the second argument:

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
        // src/Entity/Order.php
namespace App\Entity;

use Symfony\Component\Validator\Constraints as Assert;
use Symfony\Component\Validator\Context\ExecutionContextInterface;

class Order
{
    // ...

    #[Assert\Callback(
        static function (int $value, ExecutionContextInterface $context) {
            return $value >= $context->getObject()->subtotal;
        },
        message: 'The total must be equal to or greater than the subtotal.',
    )]
    public int $total;
}
    

The closure can also add its own violations to the execution context, as explained in the next section. Those violations are independent from the one added automatically when the closure returns false.

Callbacks in Class Methods

Instead of a closure, you can define the callback as a method of the class, which is called during the validation process. The method receives an ExecutionContextInterface object that lets you add violations and determine to which property they should be attributed:

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
        // src/Entity/Author.php
namespace App\Entity;

use Symfony\Component\Validator\Constraints as Assert;
use Symfony\Component\Validator\Context\ExecutionContextInterface;

class Author
{
    #[Assert\Callback]
    public function validate(ExecutionContextInterface $context, mixed $payload): void
    {
        // ...
    }
}
    

        1
2
3
4
5
        # config/validator/validation.yaml
App\Entity\Author:
    constraints:
        - Callback:
            callback: validate
    

        1
2
3
4
5
6
7
8
9
10
11
12
        <!-- 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">
        <constraint name="Callback">
            <option name="callback">validate</option>
        </constraint>
    </class>
</constraint-mapping>
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
        // 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): void
    {
        $metadata->addConstraint(new Assert\Callback('validate'));
    }

    public function validate(ExecutionContextInterface $context, mixed $payload): void
    {
        // ...
    }
}
    

The callback method itself doesn't fail or return any value. Instead, it adds "violations" to the execution context:

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
        // ...
use Symfony\Component\Validator\Context\ExecutionContextInterface;

class Author
{
    // ...
    private string $firstName;

    public function validate(ExecutionContextInterface $context, mixed $payload): void
    {
        // somehow you have an array of "fake names"
        $fakeNames = [/* ... */];

        // check if the name is actually a fake name
        if (in_array($this->getFirstName(), $fakeNames)) {
            $context->buildViolation('This name sounds totally fake!')
                ->atPath('firstName')
                ->addViolation();
        }
    }
}
    

Static Callbacks

You can also use the constraint with static methods. Since static methods don't have access to the object instance, they receive the object as the first argument:

        1
2
3
4
5
6
7
8
9
10
11
12
13
        public static function validate(mixed $value, ExecutionContextInterface $context, mixed $payload): void
{
    // somehow you have an array of "fake names"
    $fakeNames = [/* ... */];

    // check if the name is actually a fake name
    if (in_array($value->getFirstName(), $fakeNames)) {
        $context->buildViolation('This name sounds totally fake!')
            ->atPath('firstName')
            ->addViolation()
        ;
    }
}
    

External Callbacks and Closures

If you want to execute a static callback method that is not located in the class of the validated object, you can configure the constraint to invoke an array callable as supported by PHP's call_user_func function. Suppose your validation function is Acme\Validator::validate():

        1
2
3
4
5
6
7
8
9
10
11
        namespace Acme;

use Symfony\Component\Validator\Context\ExecutionContextInterface;

class Validator
{
    public static function validate(mixed $value, ExecutionContextInterface $context, mixed $payload): void
    {
        // ...
    }
}
    

You can then use the following configuration to invoke this validator:

        1
2
3
4
5
6
7
8
9
10
        // src/Entity/Author.php
namespace App\Entity;

use Acme\Validator;
use Symfony\Component\Validator\Constraints as Assert;

#[Assert\Callback([Validator::class, 'validate'])]
class Author
{
}
    

        1
2
3
4
5
        # config/validator/validation.yaml
App\Entity\Author:
    constraints:
        - Callback:
            callback: [Acme\Validator, validate]
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
        <!-- 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">
        <constraint name="Callback">
            <option name="callback">
                <value>Acme\Validator</value>
                <value>validate</value>
            </option>
        </constraint>
    </class>
</constraint-mapping>
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
        // src/Entity/Author.php
namespace App\Entity;

use Acme\Validator;
use Symfony\Component\Validator\Constraints as Assert;
use Symfony\Component\Validator\Mapping\ClassMetadata;

class Author
{
    public static function loadValidatorMetadata(ClassMetadata $metadata): void
    {
        $metadata->addConstraint(new Assert\Callback(
            callback: [Validator::class, 'validate'],
        ));
    }
}
    

Note

The Callback constraint does not support global callback functions nor is it possible to specify a global function or a service method as a callback. To validate using a service, you should create a custom validation constraint and add that new constraint to your class.

When configuring the constraint via PHP, you can also pass a closure to the constructor of the Callback constraint:

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
        // src/Entity/Author.php
namespace App\Entity;

use Symfony\Component\Validator\Constraints as Assert;
use Symfony\Component\Validator\Context\ExecutionContextInterface;
use Symfony\Component\Validator\Mapping\ClassMetadata;

class Author
{
    public static function loadValidatorMetadata(ClassMetadata $metadata): void
    {
        $callback = function (mixed $value, ExecutionContextInterface $context, mixed $payload): void {
            // ...
        };

        $metadata->addConstraint(new Assert\Callback($callback));
    }
}
    

Warning

Using a Closure together with attribute configuration will disable the attribute cache for that class/property/method because Closure cannot be cached. For best performance, it's recommended to use a static callback method.

Options

`callback`

type: string, array or Closure

The callback option accepts three different formats for specifying the callback method:

A string containing the name of a concrete or static method;
An array callable with the format ['<Class>', '<method>'];
A closure.

Concrete callbacks receive an ExecutionContextInterface instance as the first argument and the payload option as the second argument.

Static or closure callbacks receive the validated object or property value as the first argument, the ExecutionContextInterface instance as the second argument and the payload option as the third argument.

`groups`

type: array | string default: null

It defines the validation group or groups of this constraint. Read more about validation groups.

`message`

type: string default: null

By default, the return value of the callback is ignored. When this option is set, the callback must return a boolean and a violation with this message is added when it returns false. This is what allows defining callbacks directly in class properties.

You can use the following parameters in this message:

Parameter	Description
`{{ value }}`	The current (invalid) value

`payload`

type: mixed default: null

This option can be used to attach arbitrary domain-specific data to a constraint. The configured payload is not used by the Validator component, but its processing is completely up to you.

For example, you may want to use several error levels to present failed constraints differently in the front-end depending on the severity of the error.

This work, including the code samples, is licensed under a Creative Commons BY-SA 3.0 license.

TOC

Version