b2pweb / bdf-serializer
Bdf Serializer component
Installs: 13 498
Dependents: 4
Suggesters: 0
Security: 0
Stars: 0
Watchers: 2
Forks: 0
Open Issues: 2
Requires
- php: ~7.1 | ~8.0.0 | ~8.1.0 | ~8.2.0 | ~8.3.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
- vimeo/psalm: ~4.19
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)
This package is auto-updated.
Last update: 2024-11-11 15:08:52 UTC
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 functionversion_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 anError
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}