README

Serializes and deserializes complex data structures to and from json. Ideas taken from Symfony's Serializer component, Serde and others.

Symfony serializer was very flexible, but also very slow. This library tries to be as fast as possible.

Supports modern PHP projects with fully typed properties. Older codebases with no types would not work.

Benchmarks comparing this library with Symfony Serializer and Serde can be found here: Here

• Fast serialization library
  • Installation
  • Features
    • Serialization
    • Deserialization
    • Caching - optional, but highly recommended, otherwise the library will be slow
    • Custom object property serialized name
    • Serialization groups
    • Deserialization groups
    • Custom date format
    • Enforce date format
    • Convert date to timezone
    • Ignore property
    • Handling of NULL values
    • Support for json serializable objects
    • Support for Symfony Serializer attributes
  • Build, run & test locally

Installation

composer require vuryss/serializer

The library supports Symfony 7.4 LTS and Symfony 8.x.

Features

Serialization

• Properties are serialized if they are either public or have a getter method.

$person = new Person();
$person->firstName = 'Maria';
$person->lastName = 'Valentina';
$person->age = 36;
$person->isStudent = false;

$serializer = new Serializer();
$json = $serializer->serialize($person);
// {"firstName":"Maria","lastName":"Valentina","age":36,"isStudent":false}

Deserialization

• Properties are deserialized if they are public, instantiable in public constructor or have a setter method.

$json = '{"firstName":"Maria","lastName":"Valentina","age":36,"isStudent":false}';
$serializer = new Serializer();
$person = $serializer->deserialize($json, Person::class);

Caching - optional, but highly recommended, otherwise the library will be slow

Supports PSR-6 CacheItemPoolInterface: https://www.php-fig.org/psr/psr-6/#cacheitempoolinterface

No need to chain in-memory cache with external cache, the library will do it for you. Cache will be called once per used class (used in serialization or deserialization), then will be cached in memory until the script ends.

$pst6cache = new CacheItemPool(); // Some PSR-6 cache implementation
$serializer = new Serializer(
    metadataExtractor: new CachedMetadataExtractor(
        new MetadataExtractor(),
        $pst6cache,
    ),
);

Custom object property serialized name

class SomeClass
{
    #[SerializerContext(name: 'changedPropertyName')]
    public string $someProperty;
}

Serialization groups

use Vuryss\Serializer\Context;

class SomeClass
{
    #[SerializerContext(groups: ['group1'])]
    public string $property1;

    // Has implicit group 'default'
    public string $property2;
}


$serializer = new Serializer();
$object = new SomeClass();
$object->property1 = 'value1';
$object->property2 = 'value2';
$serializer->serialize($object, context: [Context::GROUPS => ['group1']]); // {"property1":"value1"}

Deserialization groups

use Vuryss\Serializer\Context;

class SomeClass
{
    #[SerializerContext(groups: ['group1'])]
    public string $property1;

    // Has implicit group 'default'
    public string $property2;
}


$serializer = new Serializer();
$data = '{"property1":"value1","property2":"value2"}';
$object = $serializer->deserialize($data, SomeClass::class, context: [Context::GROUPS => ['group1']]);
isset($object->property1); // true
isset($object->property2); // false

Custom date format

On serialization the format will always be respected. On deserialization the format will be used to parse the date. However on deserialization by default if the date is not in the provided format, it will be parsed as is, given that DateTime constructor can parse it.

Per property:

use Vuryss\Serializer\Context;

class SomeClass
{
    #[SerializerContext(context: [Context::DATETIME_FORMAT => 'Y-m-d'])]
    public DateTime $someDate;
}

Or globally:

use Vuryss\Serializer\Context;

$serializer = new Serializer(
    context: [
        Context::DATETIME_FORMAT => \DateTimeInterface::RFC2822,
    ]
);

Enforce date format

If strict data time format is required during deserialization then, you can use the Context::DATETIME_FORMAT_STRICT context option:

Per property:

use Vuryss\Serializer\Context;

class SomeClass
{
    #[SerializerContext(context: [
        Context::DATETIME_FORMAT => 'Y-m-d',
        Context::DATETIME_FORMAT_STRICT => true
    ])]
    public DateTime $someDate;
}

Or globally:

use Vuryss\Serializer\Context;

$serializer = new Serializer(
    context: [
        Context::DATETIME_FORMAT => 'Y-m-d',
        Context::DATETIME_FORMAT_STRICT => true
    ]
);

Convert date to timezone

After denormalization, the DateTime object can be converted to a specific timezone.

Per property:

use Vuryss\Serializer\Context;

class SomeClass
{
    #[SerializerContext(context: [Context::DATETIME_TARGET_TIMEZONE => 'UTC'])]
    public DateTime $someDate;
}

Or globally:

use Vuryss\Serializer\Context;

$serializer = new Serializer(
    context: [
        Context::DATETIME_TARGET_TIMEZONE => 'UTC',
    ]
);

Ignore property

Those properties will not be included in the serialized values during serialization and will not be populated with provided values during deserialization.

class SomeClass
{
    #[SerializerContext(ignore: true)]
    public string $someProperty;
}

Handling of NULL values

• By default, NULL values are included in the serialized value.

To disable this you can use the Context::SKIP_NULL_VALUES context option:

Per property:

use Vuryss\Serializer\Context;

class SomeClass
{
    #[SerializerContext(context: [Context::SKIP_NULL_VALUES => true])]
    public ?string $someProperty;
}

Or globally:

use Vuryss\Serializer\Context;

$serializer = new Serializer(
    context: [
        Context::SKIP_NULL_VALUES => true,
    ]
);

Support for json serializable objects

If an object implements the JsonSerializable interface, the jsonSerialize method will be called and the result will be serialized.

Support for Symfony Serializer attributes

This library aims to be a drop-in replacement for Symfony Serializer. It supports the following attributes:

• Groups
• SerializedName
• Ignore
• DiscriminatorMap

Build, run & test locally

To enter the prepared container environment:

docker-compose up -d
docker-compose exec library bash

Install package dependencies:

docker-compose exec library composer install -o

Run the default local quality suite against the locked latest dependencies (Symfony 8.x):

docker-compose exec library composer qa

Reproduce the Symfony compatibility matrix locally when needed:

docker-compose exec library composer deps:lowest
docker-compose exec library composer qa
docker-compose exec library composer deps:highest
docker-compose exec library composer qa

composer deps:lowest rewrites composer.lock to the minimum supported dependency set, while composer deps:highest restores the latest supported set.

HTML Coverage locally:

docker-compose exec library XDEBUG_MODE=coverage vendor/bin/pest --coverage --coverage-html=coverage