How to Create your Custom Normalizer

Creating a New Normalizer

Imagine you want add, modify, or remove some properties during the serialization process. For that you'll have to create your own normalizer. But it's usually preferable to let Symfony normalize the object, then hook into the normalization to customize the normalized data. To do that, leverage the ObjectNormalizer:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

// src/Serializer/TopicNormalizer.php
namespace App\Serializer;

use App\Entity\Topic;
use Symfony\Component\Routing\Generator\UrlGeneratorInterface;
use Symfony\Component\Serializer\Normalizer\NormalizerAwareInterface;
use Symfony\Component\Serializer\Normalizer\NormalizerAwareTrait;
use Symfony\Component\Serializer\Normalizer\NormalizerInterface;
use Symfony\Component\Serializer\Normalizer\ObjectNormalizer;

class TopicNormalizer implements NormalizerInterface
{
    public function __construct(
        private UrlGeneratorInterface $router,
        private ObjectNormalizer $normalizer,
    ) {
    }

    public function normalize(mixed $object, ?string $format = null, array $context = []): array
    {
        $data = $this->normalizer->normalize($object, $format, $context);

        // Here, add, edit, or delete some data:
        $data['href']['self'] = $this->router->generate('topic_show', [
            'id' => $object->getId(),
        ], UrlGeneratorInterface::ABSOLUTE_URL);

        return $data;
    }

    public function supportsNormalization($data, ?string $format = null, array $context = []): bool
    {
        return $data instanceof Topic;
    }
}

Registering it in your Application

Before using this normalizer in a Symfony application it must be registered as a service and tagged with serializer.normalizer. If you're using the default services.yaml configuration, this is done automatically!

If you're not using autoconfigure, you have to tag the service with serializer.normalizer. You can also use this method to set a priority (higher means it's called earlier in the process):

1
2
3
4
5
6
7
8

# config/services.yaml
services:
    # ...

    App\Serializer\TopicNormalizer:
        tags:
            # register the normalizer with a high priority (called earlier)
            - { name: 'serializer.normalizer', priority: 500 }

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

<!-- config/services.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"
    xsi:schemaLocation="http://symfony.com/schema/dic/services
        https://symfony.com/schema/dic/services/services-1.0.xsd">

    <services>
        <!-- ... -->

        <service id="App\Serializer\TopicNormalizer">
            <!-- register the normalizer with a high priority (called earlier) -->
            <tag name="serializer.normalizer"
                priority="500"
            />
        </service>
    </services>
</container>

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

// config/services.php
namespace Symfony\Component\DependencyInjection\Loader\Configurator;

use App\Serializer\TopicNormalizer;

return function(ContainerConfigurator $container) {
    // ...

    // if you're using autoconfigure, the tag will be automatically applied
    $services->set(TopicNormalizer::class)
        // register the normalizer with a high priority (called earlier)
        ->tag('serializer.normalizer', [
            'priority' => 500,
        ])
    ;
};

Performance

To figure which normalizer (or denormalizer) must be used to handle an object, the Serializer class will call the supportsNormalization() (or supportsDenormalization()) of all registered normalizers (or denormalizers) in a loop.

The result of these methods can vary depending on the object to serialize, the format and the context. That's why the result is not cached by default and can result in a significant performance bottleneck.

However, most normalizers (and denormalizers) always return the same result when the object's type and the format are the same, so the result can be cached. To do so, make those normalizers (and denormalizers) implement the CacheableSupportsMethodInterface and return true when hasCacheableSupportsMethod() is called.

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

use Symfony\Component\Serializer\Normalizer\NormalizerInterface;

class MyNormalizer implements NormalizerInterface
{
    // ...

    public function getSupportedTypes(?string $format): array
    {
        return [
            'object' => null,             // doesn't support any classes or interfaces
            '*' => false,                 // supports any other types, but the decision is not cacheable
            MyCustomClass::class => true, // supports MyCustomClass and decision is cacheable
        ];
    }
}