README

lsr/serializer adds a typed object mapper, date/time and Dibi row normalizers, and Nette DI integration around Symfony Serializer.

Requirements

PHP >= 8.4.
Dibi ^5 and Symfony Serializer, PropertyInfo and PropertyAccess ^8|^7 (installed by Composer).
No PHP extensions are declared directly in this package's manifest; selected database drivers and serialization formats may need their own extensions.
The optional Lsr\Serializer\DI\SerializerExtensions integration requires Nette DI in the consuming application. nette/di ^3.2 is currently a development dependency, not a runtime requirement of this package.

Installation

composer require lsr/serializer

Mapping data without a container

require_once __DIR__ . '/vendor/autoload.php';

use Lsr\Serializer\Mapper;
use Lsr\Serializer\Normalizer\DateTimeNormalizer;
use Symfony\Component\PropertyInfo\Extractor\ReflectionExtractor;
use Symfony\Component\Serializer\Normalizer\ObjectNormalizer;
use Symfony\Component\Serializer\Serializer;

final class PlayerProfile
{
    public string $name;
    public DateTimeImmutable $joinedAt;
}

$mapper = new Mapper(new Serializer([
    new DateTimeNormalizer(),
    new ObjectNormalizer(propertyTypeExtractor: new ReflectionExtractor()),
]));

$profile = $mapper->map([
    'name' => 'Ada',
    'joinedAt' => '2026-01-01T12:00:00+00:00',
], PlayerProfile::class);

Mapper::map($data, $type, $context) delegates to Symfony's DenormalizerInterface; it does not swallow conversion errors or validate business rules. Add normalizers appropriate to your DTOs, such as Symfony's ArrayDenormalizer or BackedEnumNormalizer. See the full composition in MapperTest.

Normalizers and configuration

Lsr\Serializer\Normalizer\DateTimeNormalizer normalizes dates to RFC 3339 strings by default and accepts date strings or arrays with a date key and optional timezone when denormalizing. Its context keys are datetime_format, datetime_timezone and datetime_cast; casting supports int, float and array. A DateTimeInterface target resolves to DateTimeImmutable.
Lsr\Serializer\Normalizer\DibiRowNormalizer handles Dibi\Row values. Register it explicitly when required; it is not in the DI extension's default normalizer list.
SerializerHelper::handleCircularReference() returns an object's code, id or name property, in that order, or null. This is the DI integration's default circular-reference handler, not an identity policy for every application.

For an existing Nette DI application, register the extension under a chosen name:

extensions:
    serializer: Lsr\Serializer\DI\SerializerExtensions

SerializerExtensions registers Symfony's serializer and a mapper service. Its schema supplies reflection/serializer/constructor property extractors, date/time, enum, JSON-serializable and object normalizers, an array denormalizer, and JSON/XML/CSV encoders. Configure extractors, normalizers, denormalizers or encoders to replace the respective lists; the corresponding extraExtractors, extraNormalizers, extraDenormalizers and extraEncoders append entries. Ordering matters when multiple normalizers support the same value. Use the schema and factory wiring in the linked source when customizing context and services.

Development

CI runs on PHP 8.4 and 8.5. Install development dependencies and run the same three checks locally:

composer install --prefer-dist --no-interaction --no-progress
composer cs
vendor/bin/phpstan analyse --no-progress
vendor/bin/phpunit --no-coverage

composer cs checks PHP coding style without changing files; composer cs:fix applies fixes (composer cbf is an alias). The test script enables Xdebug coverage mode; coverage reports need a compatible coverage driver. Configuration is in phpunit.xml, phpstan.neon and .php-cs-fixer.php.

The mapper and normalizer tests operate on in-memory objects, including Dibi rows; DI tests check that serializer components can be discovered by their service tags. No database service is needed. CI disables coverage, so it does not require a coverage driver.

AI coding assistance

See LSR Skills for AI agent skills for working with the LSR framework.

License

Licensed under the MIT License.

lsr / serializer

Package info

Security

Statistics