b2pweb/bdf-serializer

Bdf Serializer component

v1.3.0 2025-07-01 07:47 UTC

Requires

• php: ~7.1 | ~8.0.0 | ~8.1.0 | ~8.2.0 | ~8.3.0 | ~8.4.0
• doctrine/instantiator: ^1.0.3|^2.0.0
• phpdocumentor/reflection-docblock: ^4.0|~5.0
• psr/simple-cache: ^1.0|~2.0|~3.0

Requires (Dev)

• doctrine/annotations: ^1.14 || ^2.0
• friendsofphp/php-cs-fixer: ^3.0
• jeremeamia/superclosure: ^2.3
• jms/serializer: ^1.0|^3.0
• phpunit/phpunit: ~8.0|~9.0
• symfony/phpunit-bridge: ~4.3|~5.0|~6.0|~7.0
• vimeo/psalm: ~4.18|~5.22

Suggests

• jeremeamia/superclosure: Required to serialize closure (~2.1)
• jms/serializer: Required to use JMS metadata (^3.0)
• symfony/cache: Required to use default cache if string path is given to builder (~4.3)

MIT

• Sébastien Tanneux

• php
• api
• serializer

README

The Bdf Serializer can normalize, hydrate / extract and encode data or object. It use doctrine/instantiator for instancing class and phpdocumentor for reading annotations.

Installation with Composer

composer require b2p/bdf-serializer

Basic usage

<?php

use Bdf\Serializer\SerializerBuilder;

$serializer = SerializerBuilder::create()->build();
$json = $serializer->toJson($object);
//...

Declare metadata

2 drivers are available. The static method called and the annotations driver.

Static method driver

Declare your static method to build metadata

<?php

use Bdf\Serializer\Metadata\Builder\ClassMetadataBuilder;
use DateTime;

class User
{
    /**
     * @var integer
     */
    private $id;
    
    /**
     * @var string
     */
    private $name;
    
    /**
     * @var DateTime
     */
    private $date;
    
    /**
     * @param ClassMetadataBuilder $builder
     */
    public static function loadSerializerMetadata($builder)
    {
        $builder->integer('id');
        $builder->string('name');
        
        // You can also add group, alias, ...
        $builder->string('name')
            ->addGroup('all')
            ->alias('user_name')
            ->since('1.0.0');
            
        // DateTime options are available
        $builder->dateTime('date')
            ->dateFormat('Y/m/d H:i')
            ->timezone('+01:00')      // Use this timezone in internal
            ->toTimezone('+00:00');   // Export date with this timezone
    }
}

Annotations driver

The annotations driver use phpdocumentor/reflection-docblock. The tag @var will be read. If no tag is found, the default type is string.

Supported tags

• var: This annotation specify the type of the property. This tag is mandatory for deserialization.
• since: Enable object versionning. The value specify starting from which version this property is available.
• until: Enable object versionning. The value specify until which version this property was available.
• SerializeIgnore: Don't serialize this property.

NOTE: If type has not been detected in the phpdoc we try to add the typed property value added in PHP 7.4

JMS/serializer driver

The driver Bdf\Serializer\Metadata\Driver\JMSAnnotationDriver allows you to use JMS drivers. The JMS metadata will be used to create Bdf metadata. Only few options of the serializer is used:

• serializedName
• readOnly
• inline
• sinceVersion
• untilVersion
• getter
• setter
• groups
• type

NOTE: The driver works with jms/serializer > v3.0 and php > v7.2

<?php

use Bdf\Serializer\Metadata\Driver\JMSAnnotationDriver;
use JMS\Serializer\Metadata\Driver\AnnotationDriver as BaseJMSAnnotationDriver;

$driver = new JMSAnnotationDriver(new BaseJMSAnnotationDriver(...));

Serialization options

The NormalizationContext contains options for normalization.

• exclude: Properties to exclude from normalization .
• include: Properties to include from normalization.
• groups: Groups of properties to include.
• null: Null value will be added if true.
• meta_type: Include the metadata "@type" in the payload.
• version: Set the version for object that support versionning serialization.The string version should be compatible with PHP function version_compare.
• circular_reference_limit: Number of circular reference. Default 1.
• remove_default_value: Don't inject the value of a property if it is set to its default value.

Date time options

• dateFormat: Normalization option to specify the format.
• dateTimezone: Use the given timezone to format date.
• timezoneHint: Denormalization option to help to detect the timezone from input string.

Available option for NormalizationContext and DenormalizationContext.

• throws_on_accessor_error: By default a value is skipped if an Error is thrown when writting or reading on a property. This option will throw error from accessor (debug purpose).

Exemple:

<?php

use \Bdf\Serializer\Context\NormalizationContext;

$object = (object)[
    "name" => "John",
    "age"  => null,
];

$builder = new \Bdf\Serializer\SerializerBuilder();
$builder->setNormalizers([new \Bdf\Serializer\Normalizer\ObjectNormalizer()]);

$serializer = $builder->build();
echo $serializer->toJson($object);
// {"name":"John"}

echo $serializer->toJson($object, [NormalizationContext::NULL => true]);
// {"name":"John","age":null}