🧬 Сериализация объектов PHP может быть лучше

Сериализация — это фундаментальный механизм в программировании, позволяющий преобразовать объект или структуру данных в формат, пригодный для хранения или передачи (чаще всего — в строку). Этот процесс необходим, когда данные нужно сохранить в файл, отправить по сети или кэшировать в распределённой системе. С появлением распределённых архитектур, межпроцессного взаимодействия и web-протоколов сериализация стала неотъемлемой частью современной разработки. Исторически сериализация развивалась вместе с эволюцией языков и стандартов передачи данных — от бинарных форматов в RPC до универсальных JSON и XML. В PHP она существует с самых ранних версий и поддерживает как встроенные типы, так и пользовательские объекты, играя важную роль в таких технологиях, как сессии, кеши и очереди.

🙅 Ограничения стандартных методов сериализации

Несмотря на удобство встроенных функций json_encode и serialize, их использование «по умолчанию» может привести к ряду проблем. json_encode плохо справляется со сложными структурами, такими как вложенные объекты, циклические зависимости или приватные свойства — они просто теряются или искажаются в процессе сериализации. Более того, JSON не содержит информации о типах, из-за чего восстановление оригинального объекта становится невозможным без дополнительной логики. В свою очередь, serialize в PHP сохраняет информацию о классах и свойствах, но генерирует небезопасную строку, уязвимую для атак при десериализации, особенно если вы принимаете сериализованные данные извне. Кроме того, формат serialize специфичен для PHP и не совместим с другими языками, что делает его непригодным для межъязыкового взаимодействия.

Также стоит избегать наивного использования методов вида toJson, toXml и им подобных. Они, как правило, реализованы «в лоб» — без учёта вложенности, контроля над форматированием, исключениями, приватными полями или отношениями между объектами.

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

Особенно тяжело обстоят дела, когда объекты содержат вложенные классы с зависимостями (например, дата-классы или value objects), или когда один и тот же объект встречается в разных местах (например, в случае циклических ссылок). В такой ситуации важен контроль над порядком восстановления, повторное использование объектов (во избежание дублирования), а иногда и учёт контекста, в котором происходит десериализация (например, права доступа или локализация). Это требует полноценной десериализационной системы, которая умеет разбирать сложные графы объектов, распознаёт типы, работает с приватными свойствами и позволяет управлять процессом на каждом этапе.

Стандартные средства PHP не предоставляют таких возможностей «из коробки», и при увеличении сложности модели десериализация быстро становится хрупкой, нерасширяемой и трудно сопровождаемой.

🫶 Спасаемся внешними инструментами

Вот три популярных библиотеки для сериализации в PHP:

1. Symfony Serializer
   Symfony Serializer — это мощная и гибкая библиотека для сериализации и десериализации данных. Она поддерживает множество форматов, включая JSON, XML, YAML и другие. Основное преимущество — возможность работы с объектами и массивами с полной настройкой. Вы можете кастомизировать процесс сериализации, игнорировать поля, обрабатывать вложенные объекты, а также легко добавлять поддержку новых форматов.
2. JMS Serializer
   JMS Serializer — это еще одна популярная библиотека для сериализации и десериализации объектов в PHP. Она предоставляет мощные возможности, включая поддержку различных форматов (JSON, XML, YAML, и других). JMS Serializer также позволяет кастомизировать процесс сериализации с помощью аннотаций и обработчиков, а также предоставляет удобный механизм для работы с циклическими зависимостями и частичной сериализацией.
3. Spiral Serializer
   Spiral Serializer — это легковесная и высокопроизводительная библиотека для сериализации данных. Она поддерживает такие форматы, как JSON, XML и другие, и ориентирована на производительность. Основное преимущество этой библиотеки — её способность эффективно работать с большими объёмами данных. Spiral Serializer идеально подходит для проектов, где важна скорость и минимальное потребление памяти при сериализации.

Все инструменты отличны по своему но, сейчас мы будем расматривать JMS так как считаю его самым мощным.

➕ Преимущества JMS Serializer:

• Гибкость и настройка: JMS Serializer позволяет полностью настроить процесс сериализации и десериализации. Используя аннотации или XML-конфигурацию, можно легко управлять тем, как и какие данные сериализуются, игнорировать ненужные поля или даже изменять их имена в выходных данных.
• Поддержка нескольких форматов: Библиотека поддерживает не только JSON и XML, но и другие форматы, такие как YAML и CSV. Это позволяет использовать одну и ту же библиотеку для различных нужд, не беспокоясь о несовместимости между форматами.
• Работа с циклическими зависимостями: JMS Serializer предоставляет встроенную поддержку для сериализации объектов с циклическими зависимостями, что делает её идеальной для сложных и взаимосвязанных объектов.
• Поддержка версии и условной сериализации: Вы можете легко управлять процессом сериализации в зависимости от версии объекта, исключать или изменять данные в зависимости от определённых условий, что полезно в многоконтекстных приложениях или при изменении структуры данных.
• Совместимость с другими фреймворками: JMS Serializer отлично интегрируется с различными PHP-фреймворками, включая Symfony и Laravel, что делает её популярным выбором для использования в крупных проектах.
• Аннотации для упрощения конфигурации: Вместо необходимости создавать сложные конфигурационные файлы, JMS Serializer позволяет использовать аннотации в классах, что упрощает настройку и делает код чище.

🖋️ Применяем сериализатор на практике

Создадим класс User, Address и CharacterTrait(не путать с трейтами PHP)

<?php

class User
{
    private string $name;
    private Address $address;
    private array $traits;
    private DateTimeImmutable $birthday;
    private Gender $gender;

    /**
     * @param CharacterTrait[] $traits
     */
    public function __construct(
        string $name,
        Address $address,
        array $traits,
        DateTimeImmutable $birthday,
        Gender $gender
    ) {
        $this->name = $name;
        $this->address = $address;
        $this->traits = $traits;
        $this->birthday = $birthday;
        $this->gender = $gender;
    }
}

class Address
{
    private string $street;
    private string $city;
    private string $country;

    public function __construct(string $street, string $city, string $country)
    {
        $this->street = $street;
        $this->city = $city;
        $this->country = $country;
    }
}

class CharacterTrait
{
    private string $trait;

    public function __construct(string $trait)
    {
        $this->trait = $trait;
    }
}

Enum Gender: string {
    case MAN = 'M';
    case WOMAN = 'W';
}

Отлично! Теперь мы имеем 3 класса но, чтобы корректно сериализовать их требуеться описать с помощью аннотаций/атрибутов, XML или Yaml. Атрибуты/аннотации предоставляет сам пакет библиотеки JMS. Я буду описывать с помощью аттрибутов. Давайте немного модифицируем наши классы.

<?php

use JMS\Serializer\Annotation as JMS;

class User
{
    #[JMS\Type('string')]
    private string $name;

    #[JMS\Type(Address::class)]
    private Address $address;

    #[JMS\Type('array<'. CharacterTrait::class .'>')]
    #[JMS\SerializedName('character_traits')]
    private array $traits;

    #[JMS\Type('DateTimeImmutable')]
    private DateTimeImmutable $birthday;
    
    #[JMS\Type('enum<'. Gender::class .'>')]
    private Gender $gender;
}

class Address
{
    #[JMS\Type('string')]
    private string $street;

    #[JMS\Type('string')]
    private string $city;

    #[JMS\Type('string')]
    private string $country;
}

class CharacterTrait
{
    #[JMS\Type('string')]
    private string $trait;
}

Теперь давайте сериализуем этот сложный агрегат в JSON.

<?php

use JMS\Serializer\Naming\IdenticalPropertyNamingStrategy;
use JMS\Serializer\Naming\SerializedNameAnnotationStrategy;
use JMS\Serializer\SerializationContext;
use JMS\Serializer\SerializerBuilder;

// Создаем инстанс сериализатора с помощью билдера
SerializerBuilder::create()
    ->enableEnumSupport() // Включаем поддержку Enum если нужно
    ->setSerializationContextFactory(function () {
        return SerializationContext::create()
            ->setSerializeNull(true);
    })
    ->setPropertyNamingStrategy(
        new SerializedNameAnnotationStrategy(
            new IdenticalPropertyNamingStrategy(),
        ),
    )
    ->build();

// Создаем объект класса User
$user = new User(
    'Mark',
    new Address('12 Khreshchatyk St.', 'Kyiv', 'Ukraine'),
    [
        new CharacterTrait('Honest'),
        new CharacterTrait('Creative'),
        new CharacterTrait('Ambitious'),
        new CharacterTrait('Empathetic'),
        new CharacterTrait('Reliable'),
    ],
    new DateTimeImmutable('now'),
);

// Выводим сериализованный в json объект User
echo $serializer->serialize($user, 'json');

{
  "name": "Mark",
  "address": {
    "street": "12 Khreshchatyk St.",
    "city": "Kyiv",
    "country": "Ukraine"
  },
  "character_traits": [
      {"trait": "Honest"},
      {"trait": "Creative"},
      {"trait": "Ambitious"},
      {"trait": "Empathetic"},
      {"trait": "Reliable"}
  ],
  "birthday": "2025-04-14T15:12:21+00:00",
  "gender": "W"
}

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

<?php

$serializer->deserialize(
    $serialized, // Сериализованная строка в json
    User::class, // Тип в который сериализатор попробует десериализовать строку
    'json' // Тип сериализованных данных
);

А что с сериализацией в другой формат? Например сериализация в XML, Yaml и тд. На момент написания статьи сериализация в Yaml невозможна. Но есть возможность сериализовать в XML, с его специфическим форматом. Возьмем все тот же объект User с его вложенностями и опишем с помощью атрибутов специальных под XML.

<?php

use JMS\Serializer\Annotation as JMS;

#[JMS\XmlRoot('user')]
class User
{
    #[JMS\Type('string')]
    #[JMS\SerializedName('name')]
    #[JMS\XmlElement(cdata: false)]
    private string $name;

    #[JMS\Type(Address::class)]
    #[JMS\SerializedName('address')]
    private Address $address;

    #[JMS\Type('array<' . CharacterTrait::class . '>')]
    #[JMS\SerializedName('character_traits')]
    #[JMS\XmlList(inline: true, entry: 'trait')]
    private array $traits;

    #[JMS\Type('DateTimeImmutable')]
    #[JMS\XmlElement(cdata: false)]
    private DateTimeImmutable $birthday;

    #[JMS\Type('enum<' . Gender::class . '>')]
    #[JMS\XmlElement(cdata: false)]
    private Gender $gender;
}

#[JMS\XmlRoot('address')]
class Address
{
    #[JMS\Type('string')]
    #[JMS\XmlElement(cdata: false)]
    private string $street;

    #[JMS\Type('string')]
    #[JMS\XmlElement(cdata: false)]
    private string $city;

    #[JMS\Type('string')]
    #[JMS\XmlAttribute]
    private string $country;
}

#[JMS\XmlRoot('trait')]
class CharacterTrait
{
    #[JMS\Type('string')]
    #[JMS\XmlValue(cdata: false)]
    private string $trait;
}

📋 Заключение

В заключение, эта статья дала обзор возможностей сериализации объектов в PHP с использованием библиотеки JMS Serializer. Мы рассмотрели, как удобно и гибко можно настроить сериализацию и десериализацию объектов в различные форматы, такие как JSON и XML, с использованием атрибутов, что значительно упрощает работу с данными и позволяет избежать многих проблем, которые могут возникнуть при использовании стандартных функций json_encode и serialize.

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

Для получения более глубоких знаний о возможностях библиотеки и различных её функциях, таких как настройка кастомных сериализаторов, обработка циклических зависимостей и многое другое, настоятельно рекомендуется ознакомиться с официальной документацией JMS Serializer.