Використання 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:

Copy

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 не може прочитати неініціалізовані властивості

Робота з циклічними посиланнями

Циклічні посилання поширені при роботі з асоційованими об'єктами:

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, коли зустрічається такий випадок:

1
2
3
4
5
6
7
8

$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"}]}

Робота з глибиною серіалізації

Серіалізатор також може виявляти вкладені об'єкти одного класу і обмежувати глибину серіалізації. Це корисно для деревовидних структур, де один і той самий об'єкт може бути вкладений декілька разів.

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

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

// ...
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"}}

Використання зворотних викликів для серіалізації властивостей за допомогою екземплярів обʼєктів

Під час серіалізації ви можете задати зворотний виклик для форматування певної властивості

об'єкта. Це можна використовувати замість визначення контексту для групи :

Copy

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 і "розпакувати" дані введення:

1
2
3
4
5

$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, щоб визначити значення за замовчуванням для відсутніх параметрів:

1
2
3
4
5
6
7
8
9
10
11

use App\Model\Person;
use Symfony\Component\Serializer\Normalizer\AbstractNormalizer;
// ...

$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.