Loading Resources ¶

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 $name;

    public static function loadValidatorMetadata(ClassMetadata $metadata)
    {
        $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 $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();