Использование Serializer в шаблонах Twig

Вы также можете сериализировать объекты в любом шаблоне Twig с помощью фильтра serialize:

1

{{ person|serialize(format = 'json') }}

Смотрите справочник twig , чтобы узнать больше.

Сконфигурируйте контекст по умолчанию

Вы можете сконфигурировать контекст по умолчанию в конфигурации фреймворка,
например, запретить дополнительные поля при десериализации:

1
2
3
4
5

# config/packages/serializer.yaml
framework:
    serializer:
        default_context:
            allow_extra_attributes: false

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

<!-- config/packages/serializer.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:serializer>
            <framework:default-context>
                <framework:allow-extra-attributes>false</framework:allow-extra-attributes>
            </framework:default-context>
        </framework:serializer>
    </framework:config>
</container>

1
2
3
4
5
6
7
8
9
10

// config/packages/serializer.php
use Symfony\Config\FrameworkConfig;

return static function (FrameworkConfig $framework): void {
    $framework->serializer()
        ->defaultContext('', [
            'allow_extra_attributes' => false,
        ])
    ;
};

1
2
3
4
5
6
7
8
9
10

use Symfony\Component\Serializer\NameConverter\CamelCaseToSnakeCaseNameConverter;
use Symfony\Component\Serializer\Normalizer\ObjectNormalizer;

// ...
$normalizers = [
    new ObjectNormalizer(null, null, null, null, null, null, [
        'allow_extra_attributes' => false,
    ]),
];
$serializer = new Serializer($normalizers, $encoders);

Передайте контекст во время сериализации/десериализации

Вы также можете сконфигурировать контекст для одного вызова serialize()/ deserialize(). Например, вы можете пропустить свойства со значением null только для одного вызова сериализатора:

1
2
3
4
5
6
7
8

use Symfony\Component\Serializer\Normalizer\AbstractObjectNormalizer;

// ...
$serializer->serialize($person, 'json', [
    AbstractObjectNormalizer::SKIP_NULL_VALUES => true
]);

// следующие вызовы к serialize() НЕ будут пропускать значения null

1
2
3
4
5

use Symfony\Component\Serializer\Context\Normalizer\DateTimeNormalizerContextBuilder;

$contextBuilder = (new DateTimeNormalizerContextBuilder())
    ->withFormat('Y-m-d H:i:s');
$serializer->serialize($something, 'json', $contextBuilder->toArray());

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

use Symfony\Component\Serializer\Context\Encoder\CsvEncoderContextBuilder;
use Symfony\Component\Serializer\Context\Normalizer\ObjectNormalizerContextBuilder;

$initialContext = [
    'custom_key' => 'custom_value',
];

$contextBuilder = (new ObjectNormalizerContextBuilder())
    ->withContext($initialContext)
    ->withGroups(['group1', 'group2']);

$contextBuilder = (new CsvEncoderContextBuilder())
    ->withContext($contextBuilder)
    ->withDelimiter(';');

$serializer->serialize($something, 'csv', $contextBuilder->toArray());

Сконфигурируйте контекст в конкретном свойстве

Наконец, вы также можете сконфигурировать значение контекста для конкретного свойства объекта. Например, для конфигурации формата времени и даты:

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

// src/Model/Person.php

// ...
use Symfony\Component\Serializer\Attribute\Context;
use Symfony\Component\Serializer\Normalizer\DateTimeNormalizer;

class Person
{
    #[Context([DateTimeNormalizer::FORMAT_KEY => 'Y-m-d'])]
    public \DateTimeImmutable $createdAt;

    // ...
}

1
2
3
4
5
6

# config/serializer/person.yaml
App\Model\Person:
    attributes:
        createdAt:
            contexts:
                - context: { datetime_format: 'Y-m-d' }

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

<!-- config/serializer/person.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<serializer xmlns="http://symfony.com/schema/dic/serializer-mapping"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://symfony.com/schema/dic/serializer-mapping
        https://symfony.com/schema/dic/serializer-mapping/serializer-mapping-1.0.xsd"
>
    <class name="App\Model\Person">
        <attribute name="createdAt">
            <context>
                <entry name="datetime_format">Y-m-d</entry>
            </context>
        </attribute>
    </class>
</serializer>

Вы также можете указать контекст, специфичный для нормализации или денормализации:

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

// src/Model/Person.php

// ...
use Symfony\Component\Serializer\Attribute\Context;
use Symfony\Component\Serializer\Normalizer\DateTimeNormalizer;

class Person
{
    #[Context(
        normalizationContext: [DateTimeNormalizer::FORMAT_KEY => 'Y-m-d'],
        denormalizationContext: [DateTimeNormalizer::FORMAT_KEY => \DateTime::RFC3339],
    )]
    public \DateTimeImmutable $createdAt;

    // ...
}

1
2
3
4
5
6
7

# config/serializer/person.yaml
App\Model\Person:
    attributes:
        createdAt:
            contexts:
                - normalizationContext: { datetime_format: 'Y-m-d' }
                  denormalizationContext: { datetime_format: !php/const \DateTime::RFC3339 }

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

<!-- config/serializer/person.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<serializer xmlns="http://symfony.com/schema/dic/serializer-mapping"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://symfony.com/schema/dic/serializer-mapping
        https://symfony.com/schema/dic/serializer-mapping/serializer-mapping-1.0.xsd"
>
    <class name="App\Model\Person">
        <attribute name="createdAt">
            <normalization-context>
                <entry name="datetime_format">Y-m-d</entry>
            </normalization-context>

            <denormalization-context>
                <entry name="datetime_format">Y-m-d\TH:i:sP</entry>
            </denormalization-context>
        </attribute>
    </class>
</serializer>

Вы также можете ограничить использование контекста для некоторых групп :

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

// src/Model/Person.php

// ...
use Symfony\Component\Serializer\Attribute\Context;
use Symfony\Component\Serializer\Attribute\Groups;
use Symfony\Component\Serializer\Normalizer\DateTimeNormalizer;

class Person
{
    #[Groups(['extended'])]
    #[Context([DateTimeNormalizer::FORMAT_KEY => \DateTime::RFC3339])]
    #[Context(
        context: [DateTimeNormalizer::FORMAT_KEY => \DateTime::RFC3339_EXTENDED],
        groups: ['extended'],
    )]
    public \DateTimeImmutable $createdAt;

    // ...
}

1
2
3
4
5
6
7
8
9

# config/serializer/person.yaml
App\Model\Person:
    attributes:
        createdAt:
            groups: [extended]
            contexts:
                - context: { datetime_format: !php/const \DateTime::RFC3339 }
                - context: { datetime_format: !php/const \DateTime::RFC3339_EXTENDED }
                  groups: [extended]

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

<!-- config/serializer/person.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<serializer xmlns="http://symfony.com/schema/dic/serializer-mapping"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://symfony.com/schema/dic/serializer-mapping
        https://symfony.com/schema/dic/serializer-mapping/serializer-mapping-1.0.xsd"
>
    <class name="App\Model\Person">
        <attribute name="createdAt">
            <group>extended</group>

            <context>
                <entry name="datetime_format">Y-m-d\TH:i:sP</entry>
            </context>
            <context>
                <entry name="datetime_format">Y-m-d\TH:i:s.vP</entry>
                <group>extended</group>
            </context>
        </attribute>
    </class>
</serializer>

Атрибут может повторяться столько раз, сколько нужно, для одного свойства.
Контекст без группы всегда применяется первым. Затем контекст для соответствующих групп объединяется в предоставленном порядке.

Если вы повторяете один и тот же контекст в нескольких свойствах, воспользуйтесь атрибутом
#[Context] в вашем классе, чтобы применить эту конфигурацию контекста ко всем свойствам класса :

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

namespace App\Model;

use Symfony\Component\Serializer\Attribute\Context;
use Symfony\Component\Serializer\Normalizer\DateTimeNormalizer;

#[Context([DateTimeNormalizer::FORMAT_KEY => \DateTime::RFC3339])]
#[Context(
    context: [DateTimeNormalizer::FORMAT_KEY => \DateTime::RFC3339_EXTENDED],
    groups: ['extended'],
)]
class Person
{
    // ...
}

Игнорирование атрибутов с использованием контекста

Вы также можете передать массив имен атрибутов для игнорирования во время выполнения с помощью
опций контекста ignored_attributes:

1
2
3
4
5
6
7
8
9

use Symfony\Component\Serializer\Normalizer\AbstractNormalizer;

// ...
$person = new Person('Jane Doe', 32, false);
$json = $serializer->serialize($person, 'json',
[
    AbstractNormalizer::IGNORED_ATTRIBUTES => ['age'],
]);
// $json содержит {"name":"Jane Doe","sportsperson":false}

Однако это может быстро привести к непредсказуемым последствиям, если использовать его чрезмерно. См. следующий раздел о группах сериализации для лучшего решения.

Использование контекста сериализации

Наконец, вы также можете воспользоваться опцией контекста attributes для выбора свойств во время выполнения:

1
2
3
4
5
6
7

use Symfony\Component\Serializer\Normalizer\AbstractNormalizer;
// ...

$json = $serializer->serialize($person, 'json', [
    AbstractNormalizer::ATTRIBUTES => ['name', 'company' => ['name']]
]);
// $json содержит {"name":"Dunglas","company":{"name":"Les-Tilleuls.coop"}}

Доступны только атрибуты, которые не игнорируются .
Если установлены группы сериализации, можно использовать только атрибуты, разрешенные этими группами.

CamelCase в snake_case

Во многих форматах принято использовать нижнее подчеркивание для разделения слов
(также известно как snake_case). Однако в приложениях Symfony принято использовать
camelCase для именования свойств.

Symfony предоставляет встроенный преобразователь имен, предназначенный для преобразования между стилями snake_case и CamelCase при сериализации и десериализации.
Вы можете использовать его вместо преобразователя имен, учитывающего метаданные,
установив настройку name_converter в значение serializer.name_converter.camel_case_to_snake_case:

1
2
3
4

# config/packages/serializer.yaml
framework:
    serializer:
        name_converter: 'serializer.name_converter.camel_case_to_snake_case'

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

<!-- config/packages/serializer.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:serializer
            name-converter="serializer.name_converter.camel_case_to_snake_case"
        />
    </framework:config>
</container>

1
2
3
4
5
6
7
8

// config/packages/serializer.php
use Symfony\Config\FrameworkConfig;

return static function (FrameworkConfig $framework): void {
    $framework->serializer()
        ->nameConverter('serializer.name_converter.camel_case_to_snake_case')
    ;
};

1
2
3
4
5
6
7
8

use Symfony\Component\Serializer\NameConverter\CamelCaseToSnakeCaseNameConverter;
use Symfony\Component\Serializer\Normalizer\ObjectNormalizer;

// ...
$normalizers = [
    new ObjectNormalizer(null, new CamelCaseToSnakeCaseNameConverter()),
];
$serializer = new Serializer($normalizers, $encoders);

Встроенные нормализаторы

Кроме нормализаторов, зарегистрированных по умолчанию (см. предыдущий раздел), компонент serializer также предоставляет некоторые дополнительные нормализаторы. Вы можете зарегистрировать их, определив сервис и обозначив его тегом serializer.normalizer . Например, для использования CustomNormalizer вам следует определить сервис вроде:

1
2
3
4
5
6
7
8
9

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

    # если вы используете автоконфигурацию, тег будет применен автоматически
    Symfony\Component\Serializer\Normalizer\CustomNormalizer:
        tags:
            # зарегистрировать нормализатор с высоким приоритетом (вызывается раньше)
            - { name: 'serializer.normalizer', priority: 500 }

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

<!-- 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="Symfony\Component\Serializer\Normalizer\CustomNormalizer">
            <!-- зарегистрировать нормализатор с высоким приоритетом (вызывается раньше) -->
            <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 Symfony\Component\Serializer\Normalizer\CustomNormalizer;

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

    // если вы используете автоконфигурацию, тег будет применен автоматически
    $services->set(CustomNormalizer::class)
        // зарегистрировать нормализатор с высоким приоритетом (вызывается раньше)
        ->tag('serializer.normalizer', [
            'priority' => 500,
        ])
    ;
};

CustomNormalizer

Этот нормализатор вызывает метод в объекте PHP при нормализации. PHP-объект должен реализовывать NormalizableInterface и/или DenormalizableInterface.

GetSetMethodNormalizer

Этот нормализатор является альтернативой стандартному ObjectNormalizer. Он читает содержание класса, вызывая "геттеры" (публичные методы, начинающиеся с get, has, is или can). Он будет денормализовать данные, вызывая конструктор и "сеттеры" (общедоступные методы, начинающиеся с set).

Объекты нормализуются к карте имен и значений (имена генерируются путем удаления префикса get из имени метода и преобразования первой буквы в строчную; например, getFirstName() -> firstName).

PropertyNormalizer

Это еще одна альтернатива ObjectNormalizer. Этот нормализатор напрямую читает и записывает публичные свойства, а также частные и защищенные свойства (как из класса, так и из всех его родительских классов), используя PHP-отражение. Он поддерживает вызов конструктора во время процесса денормализации.

Объекты нормализуются в карту имен свойств в значение свойств.

Вы также можете ограничить нормализатор, чтобы он использовал только свойства с определенной видимостью (например, только публичные свойства) с помощью опции контекста PropertyNormalizer::NORMALIZE_VISIBILITY. Вы можете установить любую комбинацию констант PropertyNormalizer::NORMALIZE_PUBLIC, PropertyNormalizer::NORMALIZE_PROTECTED и PropertyNormalizer::NORMALIZE_PRIVATE:

1
2
3
4
5
6
7
8
9
10

use Symfony\Component\Serializer\Normalizer\PropertyNormalizer;
// ...

$json = $serializer->serialize($person, 'json', [
    // серіалізувати лише публічні властивості
    PropertyNormalizer::NORMALIZE_VISIBILITY => PropertyNormalizer::NORMALIZE_PUBLIC,

    // серіалізувати публічні та захищені властивості
    PropertyNormalizer::NORMALIZE_VISIBILITY => PropertyNormalizer::NORMALIZE_PUBLIC | PropertyNormalizer::NORMALIZE_PROTECTED,
]);

Пропуск значений null

По умолчанию, Serializer будет сохранять свойства, содержащие значение null. Вы можете изменить это поведение, установив опцию контекста AbstractObjectNormalizer::SKIP_NULL_VALUES в значение true:

1
2
3
4
5
6
7
8
9
10

class Person
{
    public string $name = 'Jane Doe';
    public ?string $gender = null;
}

$jsonContent = $serializer->serialize(new Person(), 'json', [
    AbstractObjectNormalizer::SKIP_NULL_VALUES => true,
]);
// $jsonContent содержит {"name":"Jane Doe"}

Работа с неинициализированными свойствами

В PHP типизированные свойства имеют состояние uninitialized, которое отличается. от стандартного null нетипизированных свойств. Когда вы пытаетесь получить доступ к типизированному свойству до того, как придать ему явное значение, вы получаете ошибку.

Чтобы избежать ошибки при сериализации или нормализации объекта с неинициализированными свойствами, по умолчанию ObjectNormalizer перехватывает эти ошибки и игнорирует следующие свойства.

Вы можете отключить такое поведение, установив опцию контекста AbstractObjectNormalizer::SKIP_UNINITIALIZED_VALUES в значение false:

1
2
3
4
5
6
7
8
9
10

class Person {
    public string $name = 'Jane Doe';
    public string $phoneNumber; // uninitialized
}

$jsonContent = $normalizer->serialize(new Dummy(), 'json', [
    AbstractObjectNormalizer::SKIP_UNINITIALIZED_VALUES => false,
]);
// вызывает Symfony\Component\PropertyAccess\Exception\UninitializedPropertyException
// так как ObjectNormalizer не может прочитать неинициализированные свойства

Рfбота c цикличными ссылками

Цикличные ссылки распространены при работе с ассоциированными объектами:

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
36
37
38
39
40
41
42
43
44
45
46
47
48

class Organization
{
    public function __construct(
        private string $name,
        private array $members = []
    ) {
    }

    public function getName(): string
    {
        return $this->name;
    }

    public function addMember(Member $member): void
    {
        $this->members[] = $member;
    }

    public function getMembers(): array
    {
        return $this->members;
    }
}

class Member
{
    private Organization $organization;

    public function __construct(
        private string $name
    ) {
    }

    public function getName(): string
    {
        return $this->name;
    }

    public function setOrganization(Organization $organization): void
    {
        $this->organization = $organization;
    }

    public function getOrganization(): Organization
    {
        return $this->organization;
    }
}

Чтобы избежать бесконечных циклов, нормализаторы вызывают исключение CircularReferenceException, когда встречается такой случай:

$organization = new Organization('Les-Tilleuls.coop'); $member = new Member('Kévin');

$organization->addMember($member); $member->setOrganization($organization);

$jsonContent = $serializer->serialize($organization, 'json'); // вызывает CircularReferenceException

Ключ circular_reference_limit в контексте задает количество раз, которые будет сериализирован тот же объект, прежде чем считать его цикличной ссылкой. Значение по умолчанию – 1.

Вместо того чтобы вызывать исключение, цикличные ссылки можно также обрабатывать с помощью пользовательских вызываемых. Это особенно полезно при сериализации сущностей с уникальными идентификаторами:

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

use Symfony\Component\Serializer\Exception\CircularReferenceException;

$context = [
    AbstractNormalizer::CIRCULAR_REFERENCE_HANDLER => function (object $object, ?string $format, array $context): string {
        if (!$object instanceof Organization) {
            throw new CircularReferenceException('A circular reference has been detected when serializing the object of class "'.get_debug_type($object).'".');
        }

        // сериализовать вложенную Organization только с именем (а не с членами)
        return $object->getName();
    },
];

$jsonContent = $serializer->serialize($organization, 'json', $context);
// $jsonContent содержит {"name":"Les-Tilleuls.coop","members":[{"name":"K\u00e9vin", organization: "Les-Tilleuls.coop"}]}

Работа с глубиной сериализации

Сериализатор может обнаруживать вложенные объекты одного класса и ограничивать глубину сериализации. Это полезно для древовидных структур, где один и тот же объект может быть вложен несколько раз.

Например, допустим структуру данных семейного дерева:

// ... class Person { // ...

public function __construct(

private string $name, private ?self $mother

) { }

public function getName(): string { return $this->name; }

public function getMother(): ?self { return $this->mother; }

// ...

}

// ... $greatGrandmother = new Person('Elizabeth', null); $grandmother = new Person('Jane', $greatGrandmother); $mother = new Person('Sophie', $grandmother); $child = new Person('Joe', $mother);

Вы можете указать максимальную глубину для определенного свойства. Например, вы можете установить максимальную глубину как 1, чтобы всегда сериализировать только чью-то мать (а не бабушку и т.д.):

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

// src/Model/Person.php
namespace App\Model;

use Symfony\Component\Serializer\Attribute\MaxDepth;

class Person
{
    #[MaxDepth(1)]
    private ?self $mother;

    // ...
}

1
2
3
4
5

# config/serializer/person.yaml
App\Model\Person:
    attributes:
        mother:
            max_depth: 1

1
2
3
4
5
6
7
8
9
10
11

<!-- config/serializer/person.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<serializer xmlns="http://symfony.com/schema/dic/serializer-mapping"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://symfony.com/schema/dic/serializer-mapping
        https://symfony.com/schema/dic/serializer-mapping/serializer-mapping-1.0.xsd"
>
    <class name="App\Model\Person">
        <attribute name="mother" max-depth="1"/>
    </class>
</serializer>

Чтобы ограничить глубину сериализации, в контексте необходимо установить ключ AbstractObjectNormalizer::ENABLE_MAX_DEPTH в значение true (или в контексте по умолчанию, определенном в файле framework.yaml):

1
2
3
4
5
6
7
8
9
10

// ...
$greatGrandmother = new Person('Elizabeth', null);
$grandmother = new Person('Jane', $greatGrandmother);
$mother = new Person('Sophie', $grandmother);
$child = new Person('Joe', $mother);

$jsonContent = $serializer->serialize($child, null, [
    AbstractObjectNormalizer::ENABLE_MAX_DEPTH => true
]);
// $jsonContent содержит {"name":"Joe","mother":{"name":"Sophie"}}

Вы также можете сконфигурировать пользовательское вызываемое, которое будет использовано, когда будет достигнута максимальная глубина. Это может быть использовано, например, для возвращения уникального идентификатора следующего вложенного объекта, вместо того чтобы опускать свойство:

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

use Symfony\Component\Serializer\Normalizer\AbstractObjectNormalizer;
// ...

$greatGrandmother = new Person('Elizabeth', null);
$grandmother = new Person('Jane', $greatGrandmother);
$mother = new Person('Sophie', $grandmother);
$child = new Person('Joe', $mother);

// все параметры обратного вызова являются необязательными (вы можете опустить те, которые не используете)
$maxDepthHandler = function (object $innerObject, object $outerObject, string $attributeName, ?string $format = null, array $context = []): ?string {
    // вернуть только имя следующего человека в дереве
    return $innerObject instanceof Person ? $innerObject->getName() : null;
};

$jsonContent = $serializer->serialize($child, null, [
    AbstractObjectNormalizer::ENABLE_MAX_DEPTH => true,
    AbstractObjectNormalizer::MAX_DEPTH_HANDLER => $maxDepthHandler,
]);
// $jsonContent содержит {"name":"Joe","mother":{"name":"Sophie","mother":"Jane"}}

Использование обратных вызовов для сериализации свойств с помощью экземпляров объектов

Во время сериализации вы можете задать обратный вызов для форматирования определенного свойства объекта. Это можно использовать вместо определения контекста для группы :

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

$person = new Person('cordoval', 34);
$person->setCreatedAt(new \DateTime('now'));

$context = [
    AbstractNormalizer::CALLBACKS => [
        // все параметры обратного вызова являются необязательными (вы можете опустить те, которые не используете)
        'createdAt' => function (object $attributeValue, object $object, string $attributeName, ?string $format = null, array $context = []) {
            return $attributeValue instanceof \DateTime ? $attributeValue->format(\DateTime::ATOM) : '';
        },
    ],
];
$jsonContent = $serializer->serialize($person, 'json', $context);
// $jsonContent содержит {"name":"cordoval","age":34,"createdAt":"2014-03-22T09:43:12-0500"}

Требовать все свойства

По умолчанию, Serializer добавит null к свойствам, которые можно обнулить, если для них не указаны параметры. Вы можете изменить это поведение, установив опцию контекста AbstractNormalizer::REQUIRE_ALL_PROPERTIES в значение true:

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

class Person
{
    public function __construct(
        public string $firstName,
        public ?string $lastName,
    ) {
    }
}

// ...
$data = ['firstName' => 'John'];
$person = $serializer->deserialize($data, Person::class, 'json', [
    AbstractNormalizer::REQUIRE_ALL_PROPERTIES => true,
]);
// вызывает Symfony\Component\Serializer\Exception\MissingConstructorArgumentException

Сбор ошибок типа во время денормализации

При денормализации полезной нагрузки к объекту с типизированными свойствами, вы получите исключение, если полезная нагрузка содержит свойства, не имеющие такого же типа, что и объект.

Используйте COLLECT_DENORMALIZATION_ERRORS, чтобы собрать все исключения. сразу и чтобы получить объект частично денормализованным:

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

try {
    $person = $serializer->deserialize($jsonString, Person::class, 'json', [
        DenormalizerInterface::COLLECT_DENORMALIZATION_ERRORS => true,
    ]);
} catch (PartialDenormalizationException $e) {
    $violations = new ConstraintViolationList();

    /** @var NotNormalizableValueException $exception */
    foreach ($e->getErrors() as $exception) {
        $message = sprintf('The type must be one of "%s" ("%s" given).', implode(', ', $exception->getExpectedTypes()), $exception->getCurrentType());
        $parameters = [];
        if ($exception->canUseMessageForUser()) {
            $parameters['hint'] = $exception->getMessage();
        }
        $violations->add(new ConstraintViolation($message, '', $parameters, null, $exception->getPath(), null));
    }

    // ... вернуть список нарушений пользователю
}

Десериализация в существующий объект

Сериализатор также можно использовать для обновления существующего объекта. Вы можете сделать это с помощью опции контекста сериализатора object_to_populate:

1
2
3
4
5
6
7
8
9

use Symfony\Component\Serializer\Normalizer\AbstractNormalizer;

// ...
$person = new Person('Jane Doe', 59);

$serializer->deserialize($jsonData, Person::class, 'json', [
    AbstractNormalizer::OBJECT_TO_POPULATE => $person,
]);
// вместо возвращения нового объекта, обновляется $person

Десериализация интерфейсов и абстрактных классов

При работе с ассоциированными объектами свойство иногда ссылается на интерфейс или абстрактный класс. При десериализации этих свойств Serializer должен знать, какой конкретный класс будет инициализирован. Это делается с помощью дискриминаторного отображения классов.

Представьте, что есть интерфейс InvoiceItemInterface, который реализован объектами Product и Shipping. При сериализации объекта, сериализатор добавит дополнительный "атрибут дискриминатора". Этот атрибут содержит или product, или shipping. Карта класса дискриминатора сопоставляет эти имена типов с реальными именами классов PHP при десериализации:

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

namespace App\Model;

use Symfony\Component\Serializer\Attribute\DiscriminatorMap;

#[DiscriminatorMap(
    typeProperty: 'type',
    mapping: [
        'product' => Product::class,
        'shipping' => Shipping::class,
    ]
)]
interface InvoiceItemInterface
{
    // ...
}

1
2
3
4
5
6

App\Model\InvoiceItemInterface:
    discriminator_map:
        type_property: type
        mapping:
            product: 'App\Model\Product'
            shipping: 'App\Model\Shipping'

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

<?xml version="1.0" encoding="UTF-8" ?>
<serializer xmlns="http://symfony.com/schema/dic/serializer-mapping"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://symfony.com/schema/dic/serializer-mapping
        https://symfony.com/schema/dic/serializer-mapping/serializer-mapping-1.0.xsd"
>
    <class name="App\Model\InvoiceItemInterface">
        <discriminator-map type-property="type">
            <mapping type="product" class="App\Model\Product"/>
            <mapping type="shipping" class="App\Model\Shipping"/>
        </discriminator-map>
    </class>
</serializer>

Со сконфигурированной картой дискриминатора, сериализатор теперь может выбрать правильный класс для свойств, типизированных как InvoiceItemInterface:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

class InvoiceLine
{
    public function __construct(
        private InvoiceItemInterface $invoiceItem
    ) {
        $this->invoiceItem = $invoiceItem;
    }

    public function getInvoiceItem(): InvoiceItemInterface
    {
        return $this->invoiceItem;
    }

    // ...
}

// ...
$invoiceLine = new InvoiceLine(new Product());

$jsonString = $serializer->serialize($invoiceLine, 'json');
// $jsonString содержит {"type":"product",...}

$invoiceLine = $serializer->deserialize($jsonString, InvoiceLine::class, 'json');
// $invoiceLine содержит новый InvoiceLine(new Product(...))

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
36
37
38
39
40
41
42

// ...
use Symfony\Component\Serializer\Mapping\ClassDiscriminatorFromClassMetadata;
use Symfony\Component\Serializer\Mapping\Factory\ClassMetadataFactory;
use Symfony\Component\Serializer\Mapping\Loader\AttributeLoader;
use Symfony\Component\Serializer\Normalizer\ObjectNormalizer;
use Symfony\Component\Serializer\Serializer;

class InvoiceLine
{
    public function __construct(
        private InvoiceItemInterface $invoiceItem
    ) {
        $this->invoiceItem = $invoiceItem;
    }

    public function getInvoiceItem(): InvoiceItemInterface
    {
        return $this->invoiceItem;
    }

    // ...
}

// ...

// Сконфигурировать загрузчик для извлечения информации отображения, вроде DiscriminatorMap.
// Например, при использовании атрибутов PHP:
$classMetadataFactory = new ClassMetadataFactory(new AttributeLoader());
$discriminator = new ClassDiscriminatorFromClassMetadata($classMetadataFactory);
$normalizers = [
    new ObjectNormalizer($classMetadataFactory, null, null, null, $discriminator),
];

$serializer = new Serializer($normalizers, $encoders);

$invoiceLine = new InvoiceLine(new Product());

$jsonString = $serializer->serialize($invoiceLine, 'json');
// $jsonString содержит {"type":"product",...}

$invoiceLine = $serializer->deserialize($jsonString, InvoiceLine::class, 'json');
// $invoiceLine содержит новый InvoiceLine(new Product(...))

Частичная десериализация ввода (распаковка)

Сериализатор всегда десериализирует всю строку ввода в значение PHP. При подключении
к посторонним API вам часто нужна только определенная часть возвращаемого ответа.

Чтобы избежать десериализации всего ответа, вы можете использовать UnwrappingDenormalizer и "распаковать" данные ввода:

$jsonData = '{"result":"success","data":{"person":{"name": "Jane Doe","age":57}}}'; $data = $serialiser->deserialize($jsonData, Object::class, [ UnwrappingDenormalizer::UNWRAP_PATH => '[data][person]', ]); // $data - Person(name: 'Jane Doe', age: 57)

unwrap_path - это путь свойства компонента PropertyAccess, примененный к денормализованному массиву.

Работа с аргументами конструктора

Если в конструкторе класса определены аргументы, как это обычно бывает с Value Objects, сериализатор будет сопоставлять имена параметров с десериализированными атрибутами. Если некоторых параметров не хватает, будет вызвано MissingConstructorArgumentsException.

В этих случаях используйте опцию контекста default_constructor_arguments, чтобы определить значения по умолчанию для отсутствующих параметров:

use AppModelPerson; use SymfonyComponentSerializerNormalizerAbstractNormalizer; // ...

$jsonData = '{"age":39,"name":"Jane Doe"}'; $person = $serializer->deserialize($jsonData, Person::class, 'json', [ AbstractNormalizer::DEFAULT_CONSTRUCTOR_ARGUMENTS => [ Person::class => ['sportsperson' => true], ], ]); // $person - это Person(name: 'Jane Doe', age: 39, sportsperson: true);

Рекурсивная денормализация и безопасность типов

Если доступен ExtractorTypeExtractor, нормализатор также проверит, соответствуют ли данные для денормализации типу свойства (даже для примитивных типов). Например, если предоставлено string, а тип свойства - int, то будет вызвано UnexpectedValueException. Принудительное применение типов свойств можно отключить с помощью установки опции контекста сериализатора ObjectNormalizer::DISABLE_TYPE_ENFORCEMENT в значение true.

Работа с булевыми занчениями

PHP рассматривает много разных значений как истинные или ложные. Например, строки true, 1 и yes считаются истинными, тогда как false, 0 и no считаются ложными.

При десериализации компонент Serializer может позаботиться об этом автоматически. Это можно сделать с помощью опции контекста AbstractNormalizer::FILTER_BOOL:

1
2
3
4
5
6
7

use Symfony\Component\Serializer\Normalizer\AbstractNormalizer;
// ...

$person = $serializer->denormalize(['sportsperson' => 'yes'], Person::class, context: [
    AbstractNormalizer::FILTER_BOOL => true
]);
// $person содержит экземпляр Person с sportsperson, установленным как true

Этот контекст заставляет процесс десериализации вести себя как функция filter_var с флажком FILTER_VALIDATE_BOOL.