1. Документация
  2. Как использовать Сериализатор

Дата обновления перевода 2021-12-25

Как использовать Сериализатор

Symfony предоставляет Сериадизатор для сериализации/десериализации в и из объектов и разных форматов (например, JSON или XML). До его использования, прочтите документы компонента Сериализатор, который предоставляет вам некоторые инструменты, которые вы можете использовать для решения ваших задач.

Установка

В приложениях, использующих Symfony Flex, выполните эту команду, чтобы установить пакет Symfony serializer перед его использованием:

1
$ composer require symfony/serializer-pack

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

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

// src/Controller/DefaultController.php
namespace App\Controller;

use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\Serializer\SerializerInterface;

class DefaultController extends AbstractController
{
    public function index(SerializerInterface $serializer)
    {
        // продолжайте читать для примеров использования
    }
}

Или вы можете использовать фильтр Twig serialize в шаблоне:

1
{{ object|serialize(format = 'json') }}

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

New in version 5.3: Фильтр serialize был представлен в Symfony 5.3, которая использует компонент Сериализатор.

Добавление нормализаторов и кодировшиков

После подключения, сервис serializer будет доступен в контейнере. Он поставляется с набором полезных кодировщиков и нормализаторов.

Включены кодировщики, поддерживающие следующие форматы:

А также следующие нормализаторы:

Пользовательские нормализаторы и/или кодировщики также могут быть загружены, путем их тегирования serializer.normalizer и serializer.encoder. Также возможно установить приоритетность тега для того, чтобы решить порядок сопоставления.

Caution

Не забывайте загружать DateTimeNormalizer при сериализации классов DateTime или DateTimeImmutable для избежания излишнего использования памяти и оголения внутренних деталей.

Вот пример того, как загружать GetSetMethodNormalizer, более быструю альтернативу ObjectNormalizer, когда объекты данных всегда используют геттеры (getXxx()), иссеры (isXxx()) или хассеры (hasXxx()) для чтения свойств, и сеттеры (setXxx()) для изменения свойств:

  • YAML
    1
2
3
4
5
    # config/services.yaml
services:
    get_set_method_normalizer:
        class: Symfony\Component\Serializer\Normalizer\GetSetMethodNormalizer
        tags: [serializer.normalizer]
  • XML
     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
    <!-- 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="get_set_method_normalizer" class="Symfony\Component\Serializer\Normalizer\GetSetMethodNormalizer">
            <tag name="serializer.normalizer"/>
        </service>
    </services>
</container>
  • PHP
     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
    // config/services.php
namespace Symfony\Component\DependencyInjection\Loader\Configurator;

use Symfony\Component\Serializer\Normalizer\GetSetMethodNormalizer;

return function(ContainerConfigurator $configurator) {
    $services = $configurator->services();

    $services->set('get_set_method_normalizer', GetSetMethodNormalizer::class)
        ->tag('serializer.normalizer')
    ;
};

Контекст сериализатора

Сериализатор может определять контекст для контроля (де)сериализацию источников. Этот контекст передается всем нормализаторам. К примеру:

  • DateTimeNormalizer использует ключ datetime_format в формате даты и времени;
  • AbstractObjectNormalizer использует empty_iterable_as_object, чтобы представлять пустые объекты как {} вместо [] в JSON.

New in version 5.4: Использование опции empty_array_as_object в Сериализаторе по умолчанию было представлено в Symfony 5.4.

Вы можете передать контекст следующим образом:

$serializer->serialize($something, 'json', [
    DateTimeNormalizer::FORMAT_KEY => 'Y-m-d H:i:s',
]);

$serializer->deserialize($someJson, Something::class, 'json', [
    DateTimeNormalizer::FORMAT_KEY => 'Y-m-d H:i:s',
]);

Использование групповых аннотаций сериализации

Чтобы использовать аннотации, для начала добавьте их поддержку через SensioFrameworkExtraBundle:

1
$ composer require sensio/framework-extra-bundle

Далее, добавьте аннотации @Groups к вашему классу:

// src/Entity/Product.php
namespace App\Entity;

use Doctrine\ORM\Mapping as ORM;
use Symfony\Component\Serializer\Annotation\Groups;

/**
 * @ORM\Entity()
 */
class Product
{
    /**
     * @ORM\Id
     * @ORM\GeneratedValue
     * @ORM\Column(type="integer")
     * @Groups({"show_product", "list_product"})
     */
    private $id;

    /**
     * @ORM\Column(type="string", length=255)
     * @Groups({"show_product", "list_product"})
     */
    private $name;

    /**
     * @ORM\Column(type="integer")
     * @Groups({"show_product"})
     */
    private $description;
}

Теперь вы можете выбирать, какие группы использовать при сериализации:

$json = $serializer->serialize(
    $product,
    'json',
    ['groups' => 'show_product']
);

Tip

Значение ключа groups может быть одной строкой или их массивом.

В дополенение к аннотации @Groups, компонент Сериализатор также поддерживает файлы YAML или XML. Эти файлы автоматически загружаются при сохранении в одной из следующих локаций:

  • Все файлы *.yaml и *.xml в каталоге config/serializer/.
  • Файл serialization.yaml или serialization.xml в каталоге пакета Resources/config/;
  • Все файлы *.yaml и *.xml в каталоге пакета Resources/config/serialization/.

Конфигурация кеша метаданных

Метаданные для сериализатора автоматически кешируются для улучшения работы приложения. По умолчанию, сериализатор использует пул кеша cache.system, который конфигурируется с использованием опции cache.system.

Подключения конвертера имен

Использование сервиса конвертера имен может быть определено в конфигурации с использованием опции name_converter.

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

  • YAML
    1
2
3
4
5
    # config/packages/framework.yaml
framework:
    # ...
    serializer:
        name_converter: 'serializer.name_converter.camel_case_to_snake_case'
  • XML
    1
2
3
4
5
    <!-- config/packages/framework.xml -->
<framework:config>
    <!-- ... -->
    <framework:serializer name-converter="serializer.name_converter.camel_case_to_snake_case"/>
</framework:config>
  • PHP
    1
2
3
4
5
6
    // config/packages/framework.php
use Symfony\Config\FrameworkConfig;

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

Углубленное использование Сериализатора

Платформа API предоставляет API-систему, поддерживающую следующие форматы:

Она встроена над фреймворком Symfony и ее компонентом Сериализатор. Она предоставляет пользовательские нормализаторы и кодировщики, пользовательсские метаданные и систему кеширования.

Если вы хотите воспользоваться преимуществами полной мощи компонента Symfony Сериализатор, посмотрите на то, как работает этот пакет.

Эта документация является переводом официальной документации Symfony и предоставляется по свободной лицензии CC BY-SA 3.0.