Feature Mapper

🔄 Нормализация объектов

← Возможности · Главная · Сравнение

Serializer::mapper() — нормализация объект ↔ массив через рефлексию конструктора: без атрибутов и аннотаций на DTO.

Принцип работы

toArray() разворачивает объект рекурсивно (включая private и promoted свойства, enum → значение, даты → ATOM-строки). fromArray() собирает объект через конструктор, восстанавливая типы из его сигнатуры: скаляры как есть, enum через from(), DateTimeImmutable из строки, вложенные объекты по типам параметров. Рефлексия классов кэшируется (bounded — сброс при переполнении).

use CloudCastle\Serialize\Serializer;

final class OrderDto
{
    public function __construct(
        public readonly int $id,
        public readonly Status $status,
        public readonly DateTimeImmutable $createdAt,
    ) {}
}

$mapper = Serializer::mapper();

$array = $mapper->toArray($order);
// ['id' => 1, 'status' => 'paid', 'createdAt' => '2026-07-16T10:00:00+00:00']

$dto = $mapper->fromArray(OrderDto::class, $array);   // OrderDto с восстановленными типами

// Круговой цикл через JSON — типовой транспорт
$json = Serializer::json()->serialize($mapper->toArray($order));
$back = $mapper->fromArray(OrderDto::class, Serializer::json()->unserialize($json));

Плюсы

• Никаких атрибутов/аннотаций на DTO — маппинг из сигнатуры конструктора.
• Promoted и private свойства читаются корректно.
• Восстановление enum, DateTimeImmutable, вложенных объектов по типам.
• Fail-safe: отсутствующее поле, битый enum или дата — контрактное исключение с именем поля.
• Bounded-кэш рефлексии — память ограничена даже на потоке динамических классов.

Минусы

• Восстанавливает типы из сигнатуры конструктора; сложные случаи (union-типы, массивы объектов по PHPDoc) в v1 проходят как есть — для них используйте symfony/serializer.

✅ Рекомендуется

• DTO ↔ массив ↔ JSON для API и очередей без загрязнения моделей атрибутами.
• Восстановление доменных объектов из конфигов и снапшотов.

❌ Антипаттерны

• Маппинг классов с побочными эффектами в конструкторе (запросы к БД, IO) — денормализация вызовет их.
• Ожидание восстановления приватного состояния, не выражаемого через конструктор.