Annotations.md

BetterSerializer (PHP)

Annotations

For now, there aren't many annotations supported, but the plan is to implement most of the features from JMSSerializer and from Jackson. Fingers crossed :)

@Property

Defines the property name and type. Has to be defined on a class property.

Properties:

• name: defined name can override the actual property name during de/serialization
• type: type definition, most of the times it is unnecessary (because the serializer can read the @var docblock annotations), with the exception of typed collections (not implemented yet).

Example:

use BetterSerializer\DataBind\MetaData\Annotations as Serializer;

class Car
{

    /**
     * @var string
     * @Serializer\Property(name="serializedTitle", type="string")
     */
    private $title;
}

In this case the object of the class Car will have the title property named as serializedTitle in the serialized output or in the deserialized input.

The type property defines the property type. The type attribute can have parameters and parameters can be used by the serialization/deserialization process.

The following types are supported currently:

Type	Description
bool	Primitive boolean
int	Primitive integer
float	Primitive double
string	Primitive string
array	An array of type T (T can be any available type). Examples: array, array<MyNamespace\MyObject>, etc.
T[]	An array of type T (T can be any available type).
T	Where T is a class name. It either can be fully qualified, or relative to the current namespace of the parent class.
Collection	A Doctrine collection of type T, where T is a class name. It either can be fully qualified, or relative to the current namespace of the parent class. This short notation expect a use clasue with FQDN Collection.
Doctrine\Common\Collections\Collection	A Doctrine collection of type T, without the FQDN Collection use clause.
DateTime(format='Y-m-d H:i:s')	DateTime object with custom format (default format is DateTime::ATOM)
DateTimeImmutable(format='Y-m-d H:i:s')	DateTimeImmutable object with custom format (default format is DateTime::ATOM)

@BoundToProperty

Describes a relation between a given class property and a constructor parameter. Has to be defined on a constructor method for each constructor argument, whose name differs from the corresponding class parameter, which the constructor argument is bound to.

use BetterSerializer\DataBind\MetaData\Annotations as Serializer;

class Car
{

    /**
     * @var string
     */
    private $title;
    
    /**
     * @param string $specialTitle
     * @Serializer\BoundToProperty(propertyName="title", argumentName="specialTitle")
     */
    public function __construct(string $specialTitle)
    {
        $this->title = $specialTitle;
    }
}

In this case, the serializer knows, that the specialTitle constructor argument is being assigned to the title class property.

@Groups

Applicable only with serialization. You can define serialization groups into a serialization context, which will only serialize object properties, which belong to the defined groups. This feature is helpful when you don't want to serialize everything from a given object. If a property doesn't have any group defined, it automatically belongs to the default group. If a property belongs to a different group, it has to have the default group assigned as well, to be able to serialize it without using serialization context.

Example:

use BetterSerializer\DataBind\MetaData\Annotations as Serializer;
use BetterSerializer\DataBind\Writer\SerializationContext;

class Car
{

    /**
     * @var string
     * @Serializer\Groups({"group1","default"})
     */
    private $title;
    
    /**
     * @var string
     * @Serializer\Groups({"group2","default"})
     */
    private $color;
    
    /**
     * @var string
     * @Serializer\Groups({"group1","group2"})
     */
    private $serialNr;
    
    /**
     * @var int
     */
    private $year;
}

$serializer->serialize($data, SerializationType::JSON(), new SerializationContext(['group1']));
// will contain title, serialNr

$serializer->serialize($data, SerializationType::JSON(), new SerializationContext(['group2']));
// will contain color, serialNr

$serializer->serialize($data, SerializationType::JSON(), new SerializationContext(['group1', 'group2']));
// will contain title, color, serialNr

$serializer->serialize($data, SerializationType::JSON());
// will contain title, color, year