The StaticMethodLoader

The most basic loader is the StaticMethodLoader. This loader gets the metadata by calling a static method of the class. The name of the method is configured using the addMethodMapping() method of the validator builder:

1
2
3
4
5

use Symfony\Component\Validator\Validation;

$validator = Validation::createValidatorBuilder()
    ->addMethodMapping('loadValidatorMetadata')
    ->getValidator();

In this example, the validation metadata is retrieved executing the loadValidatorMetadata() method of the class:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

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

class User
{
    protected string $name;

    public static function loadValidatorMetadata(ClassMetadata $metadata): void
    {
        $metadata->addPropertyConstraint('name', new Assert\NotBlank());
        $metadata->addPropertyConstraint('name', new Assert\Length([
            'min' => 5,
            'max' => 20,
        ]));
    }
}

The File Loaders

The component also provides two file loaders, one to load YAML files and one to load XML files. Use addYamlMapping() or addXmlMapping() to configure the locations of these files:

1
2
3
4
5

use Symfony\Component\Validator\Validation;

$validator = Validation::createValidatorBuilder()
    ->addYamlMapping('validator/validation.yaml')
    ->getValidator();

The AnnotationLoader

At last, the component provides an AnnotationLoader to get the metadata from the annotations of the class. Annotations are defined as @ prefixed classes included in doc block comments (/** ... */). For example:

1
2
3
4
5
6
7
8
9
10

use Symfony\Component\Validator\Constraints as Assert;
// ...

class User
{
    /**
     * @Assert\NotBlank
     */
    protected string $name;
}

To enable the annotation loader, call the enableAnnotationMapping() method. If you use annotations instead of attributes, it's also required to call addDefaultDoctrineAnnotationReader() to use Doctrine's annotation reader:

1
2
3
4
5
6

use Symfony\Component\Validator\Validation;

$validator = Validation::createValidatorBuilder()
    ->enableAnnotationMapping()
    ->addDefaultDoctrineAnnotationReader() // add this only when using annotations
    ->getValidator();

To disable the annotation loader after it was enabled, call disableAnnotationMapping().

1
2
3
4
5
6
7
8
9

use Composer\Autoload\ClassLoader;
use Doctrine\Common\Annotations\AnnotationRegistry;

/** @var ClassLoader $loader */
$loader = require __DIR__.'/../vendor/autoload.php';

AnnotationRegistry::registerLoader([$loader, 'loadClass']);

return $loader;

Using Multiple Loaders

The component provides a LoaderChain class to execute several loaders sequentially in the same order they were defined:

The ValidatorBuilder will already take care of this when you configure multiple mappings:

1
2
3
4
5
6
7
8

use Symfony\Component\Validator\Validation;

$validator = Validation::createValidatorBuilder()
    ->enableAnnotationMapping(true)
    ->addDefaultDoctrineAnnotationReader()
    ->addMethodMapping('loadValidatorMetadata')
    ->addXmlMapping('validator/validation.xml')
    ->getValidator();

Caching

Using many loaders to load metadata from different places is convenient, but it can slow down your application because each file needs to be parsed, validated and converted into a ClassMetadata instance.

To solve this problem, call the setMappingCache() method of the Validator builder and pass your own caching class (which must implement the PSR-6 interface CacheItemPoolInterface):

1
2
3
4
5
6

use Symfony\Component\Validator\Validation;

$validator = Validation::createValidatorBuilder()
    // ... add loaders
    ->setMappingCache(new SomePsr6Cache())
    ->getValidator();

Using a Custom MetadataFactory

All the loaders and the cache are passed to an instance of LazyLoadingMetadataFactory. This class is responsible for creating a ClassMetadata instance from all the configured resources.

You can also use a custom metadata factory implementation by creating a class which implements MetadataFactoryInterface. You can set this custom implementation using setMetadataFactory():

1
2
3
4
5
6

use Acme\Validation\CustomMetadataFactory;
use Symfony\Component\Validator\Validation;

$validator = Validation::createValidatorBuilder()
    ->setMetadataFactory(new CustomMetadataFactory(...))
    ->getValidator();