Annotations¶

@ExclusionPolicy¶

This annotation can be defined on a class to indicate the exclusion strategy that should be used for the class.

@Exclude¶

This annotation can be defined on a property or a class to indicate that the property or class should not be serialized/unserialized. Works only in combination with NoneExclusionPolicy.

If the ExpressionLanguageExclusionStrategy exclusion strategy is enabled, it will be possible to use @Exclude(if="expression") to exclude dynamically a property or an object if used on class level.

@Expose¶

This annotation can be defined on a property to indicate that the property should be serialized/unserialized. Works only in combination with AllExclusionPolicy.

If the ExpressionLanguageExclusionStrategy exclusion strategy is enabled, will be possible to use @Expose(if="expression") to expose dynamically a property.

@SkipWhenEmpty¶

This annotation can be defined on a property to indicate that the property should not be serialized if the result will be ?empty?.

Works option works only when serializing.

@SerializedName¶

This annotation can be defined on a property to define the serialized name for a property. If this is not defined, the property will be translated from camel-case to a lower-cased underscored name, e.g. camelCase -> camel_case.

Note that this annotation is not used when you?re using any other naming strategy than the default configuration (which includes the SerializedNameAnnotationStrategy). In order to re-enable the annotation, you will need to wrap your custom strategy with the SerializedNameAnnotationStrategy.

<?php
$serializer = \JMS\Serializer\SerializerBuilder::create()
    ->setPropertyNamingStrategy(
        new \JMS\Serializer\Naming\SerializedNameAnnotationStrategy(
            new \JMS\Serializer\Naming\IdenticalPropertyNamingStrategy()
        )
    )
    ->build();

@Since¶

This annotation can be defined on a property to specify starting from which version this property is available. If an earlier version is serialized, then this property is excluded automatically. The version must be in a format that is understood by PHP?s version_compare function.

@Until¶

This annotation can be defined on a property to specify until which version this property was available. If a later version is serialized, then this property is excluded automatically. The version must be in a format that is understood by PHP?s version_compare function.

@Groups¶

This annotation can be defined on a property to specify if the property should be serialized when only serializing specific groups (see Exclusion Strategies).

@MaxDepth¶

This annotation can be defined on a property to limit the depth to which the content will be serialized. It is very useful when a property will contain a large object graph.

@AccessType¶

This annotation can be defined on a property, or a class to specify in which way the properties should be accessed. By default, the serializer will retrieve, or set the value via reflection, but you may change this to use a public method instead:

<?php
use JMS\Serializer\Annotation\AccessType;

/** @AccessType("public_method") */
class User
{
    private $name;

    public function getName()
    {
        return $this->name;
    }

    public function setName($name)
    {
        $this->name = trim($name);
    }
}

@Accessor¶

This annotation can be defined on a property to specify which public method should be called to retrieve, or set the value of the given property:

<?php
use JMS\Serializer\Annotation\Accessor;

class User
{
    private $id;

    /** @Accessor(getter="getTrimmedName",setter="setName") */
    private $name;

    // ...
    public function getTrimmedName()
    {
        return trim($this->name);
    }

    public function setName($name)
    {
        $this->name = $name;
    }
}

@AccessorOrder¶

This annotation can be defined on a class to control the order of properties. By default the order is undefined, but you may change it to either ?alphabetical?, or ?custom?.

<?php
use JMS\Serializer\Annotation\AccessorOrder;

/**
 * @AccessorOrder("alphabetical")
 *
 * Resulting Property Order: id, name
 */
class User
{
    private $id;
    private $name;
}

/**
 * @AccessorOrder("custom", custom = {"name", "id"})
 *
 * Resulting Property Order: name, id
 */
class User
{
    private $id;
    private $name;
}

/**
 * @AccessorOrder("custom", custom = {"name", "someMethod" ,"id"})
 *
 * Resulting Property Order: name, mood, id
 */
class User
{
    private $id;
    private $name;

    /**
     * @Serializer\VirtualProperty
     * @Serializer\SerializedName("mood")
     *
     * @return string
     */
    public function getSomeMethod()
    {
        return 'happy';
    }
}

@VirtualProperty¶

This annotation can be defined on a method to indicate that the data returned by the method should appear like a property of the object.

A virtual property can be defined for a method of an object to serialize and can be also defined at class level exposing data using the Symfony Expression Language.

/**
 * @Serializer\VirtualProperty(
 *     "firstName",
 *     exp="object.getFirstName()",
 *     options={@Serializer\SerializedName("my_first_name")}
 *  )
 */
class Author
{
    /**
     * @Serializer\Expose()
     */
    private $id;

    /**
     * @Serializer\Exclude()
     */
    private $firstName;

    /**
     * @Serializer\Exclude()
     */
    private $lastName;

    /**
     * @Serializer\VirtualProperty()
     */
    public function getLastName()
    {
        return $this->lastName;
    }

    public function getFirstName()
    {
        return $this->firstName;
    }
}

In this example:

• id is exposed using the object reflection.
• lastName is exposed using the getLastName getter method.
• firstName is exposed using the object.getFirstName() expression (exp can contain any valid symfony expression).

@VirtualProperty() can also have an optional property name, used to define the internal property name (for sorting proposes as example). When not specified, it defaults to the method name with the ?get? prefix removed.

In PHP 8, due to the missing support for nested annotations, in the options array you need to pass an array with the class name and an array with the arguments for its constructor.

/**
 * @Serializer\VirtualProperty(
 *     "firstName",
 *     exp="object.getFirstName()",
 *     options={@Serializer\SerializedName("my_first_name")}
 *  )
 */
#[Serializer\VirtualProperty(name: "firstName", exp: "object.getFirstName()", options: [[Serializer\SerializedName::class, ["my_first_name"]]])]
class Author
{
...

@Inline¶

This annotation can be defined on a property to indicate that the data of the property should be inlined.

Note: AccessorOrder will be using the name of the property to determine the order.

@ReadOnlyProperty¶

This annotation can be defined on a property to indicate that the data of the property is read only and cannot be set during deserialization.

A property can be marked as non read only with @ReadOnlyProperty(false) annotation (useful when a class is marked as read only).

@PreSerialize¶

This annotation can be defined on a method which is supposed to be called before the serialization of the object starts.

@PostSerialize¶

This annotation can be defined on a method which is then called directly after the object has been serialized.

@PostDeserialize¶

This annotation can be defined on a method which is supposed to be called after the object has been deserialized.

@Discriminator¶

This annotation allows serialization/deserialization of relations which are polymorphic, but where a common base class exists. The @Discriminator annotation has to be applied to the least super type:

/**
 * @Discriminator(field = "type", disabled = false, map = {"car": "Car", "moped": "Moped"}, groups={"foo", "bar"})
 */
abstract class Vehicle { }
class Car extends Vehicle { }
class Moped extends Vehicle { }

@Type¶

This annotation can be defined on a property to specify the type of that property. For deserialization, this annotation must be defined. The @Type annotation can have parameters and parameters can be used by serialization/deserialization handlers to enhance the serialization or deserialization result; for example, you may want to force a certain format to be used for serializing DateTime types and specifying at the same time a different format used when deserializing them.

Available Types:

(*) If the standalone jms/serializer is used then default format is DateTime::ISO8601 (which is not compatible with ISO-8601 despite the name). For jms/serializer-bundle the default format is DateTime::ATOM (the real ISO-8601 format) but it can be changed in configuration.

(**) The key type K for array-linke formats as array. ArrayCollection, iterable, etc., is only used for deserialization, for serializaiton is treated as string.

Examples:

<?php

namespace MyNamespace;

use JMS\Serializer\Annotation\Type;

class BlogPost
{
    /**
     * @Type("ArrayCollection<MyNamespace\Comment>")
     */
    private $comments;

    /**
     * @Type("string")
     */
    private $title;

    /**
     * @Type("MyNamespace\Author")
     */
    private $author;

    /**
     * @Type("DateTime")
     */
    private $startAt;

    /**
     * @Type("DateTime<'Y-m-d'>")
     */
    private $endAt;

    /**
     * @Type("DateTime<'Y-m-d', '', ['Y-m-d', 'Y/m/d']>")
     */
    private $publishedAt;

    /**
     * @Type("DateTimeImmutable")
     */
    private $createdAt;

    /**
     * @Type("DateTimeImmutable<'Y-m-d'>")
     */
    private $updatedAt;

    /**
     * @Type("DateTimeImmutable<'Y-m-d', '', ['Y-m-d', 'Y/m/d']>")
     */
    private $deletedAt;

    /**
     * @Type("boolean")
     */
    private $published;

    /**
     * @Type("array<string, string>")
     */
    private $keyValueStore;
}

@XmlRoot¶

This allows you to specify the name of the top-level element.

<?php

use JMS\Serializer\Annotation\XmlRoot;

/** @XmlRoot("user") */
class User
{
    private $name = 'Johannes';
}

Resulting XML:

<user>
    <name><![CDATA[Johannes]]></name>
</user>

@XmlAttribute¶

This allows you to mark properties which should be set as attributes, and not as child elements.

<?php

use JMS\Serializer\Annotation\XmlAttribute;

class User
{
    /** @XmlAttribute */
    private $id = 1;
    private $name = 'Johannes';
}

Resulting XML:

<result id="1">
    <name><![CDATA[Johannes]]></name>
</result>

@XmlDiscriminator¶

This annotation allows to modify the behaviour of @Discriminator regarding handling of XML.

Available Options:

Example for ?attribute?:

<?php

use JMS\Serializer\Annotation\Discriminator;
use JMS\Serializer\Annotation\XmlDiscriminator;

/**
 * @Discriminator(field = "type", map = {"car": "Car", "moped": "Moped"}, groups={"foo", "bar"})
 * @XmlDiscriminator(attribute=true)
 */
abstract class Vehicle { }
class Car extends Vehicle { }

Resulting XML:

<vehicle type="car" />

Example for ?cdata?:

<?php

use JMS\Serializer\Annotation\Discriminator;
use JMS\Serializer\Annotation\XmlDiscriminator;



/**
 * @Discriminator(field = "type", map = {"car": "Car", "moped": "Moped"}, groups={"foo", "bar"})
 * @XmlDiscriminator(attribute=true)
 */
abstract class Vehicle { }
class Car extends Vehicle { }

Resulting XML:

<vehicle><type>car</type></vehicle>

@XmlValue¶

This allows you to mark properties which should be set as the value of the current element. Note that this has the limitation that any additional properties of that object must have the @XmlAttribute annotation. XMlValue also has property cdata. Which has the same meaning as the one in XMLElement.

<?php

use JMS\Serializer\Annotation\XmlAttribute;
use JMS\Serializer\Annotation\XmlValue;
use JMS\Serializer\Annotation\XmlRoot;

/** @XmlRoot("price") */
class Price
{
    /** @XmlAttribute */
    private $currency = 'EUR';

    /** @XmlValue */
    private $amount = 1.23;
}

Resulting XML:

<price currency="EUR">1.23</price>

@XmlList¶

This allows you to define several properties of how arrays should be serialized. This is very similar to @XmlMap, and should be used if the keys of the array are not important.

<?php

use JMS\Serializer\Annotation\XmlList;
use JMS\Serializer\Annotation\XmlRoot;

/** @XmlRoot("post") */
class Post
{
    /**
     * @XmlList(inline = true, entry = "comment")
     */
    private $comments = [];

    public function __construct(array $comments)
    {
        $this->comments = $comments;
    }
}

class Comment
{
    private $text;

    public function __construct(string $text)
    {
        $this->text = $text;
    }
}

// usage
$post = new Post(
    new Comment('Foo'),
    new Comment('Bar'),
);
$xml = $serializer->serialize($post, 'xml');

Resulting XML:

<post>
    <comment>
        <text><![CDATA[Foo]]></text>
    </comment>
    <comment>
        <text><![CDATA[Bar]]></text>
    </comment>
</post>

You can also specify the entry tag namespace using the namespace attribute (@XmlList(inline = true, entry = "comment", namespace="http://www.example.com/ns")).

@XmlMap¶

Similar to @XmlList, but the keys of the array are meaningful.

@XmlKeyValuePairs¶

This allows you to use the keys of an array as xml tags.

@XmlAttributeMap¶

This is similar to the @XmlKeyValuePairs, but instead of creating child elements, it creates attributes.

<?php

use JMS\Serializer\Annotation\XmlAttribute;

class Input
{
    /** @XmlAttributeMap */
    private $id = array(
        'name' => 'firstname',
        'value' => 'Adrien',
    );
}

Resulting XML:

<result name="firstname" value="Adrien"/>

@XmlElement¶

This annotation can be defined on a property to add additional xml serialization/deserialization properties.

<?php

use JMS\Serializer\Annotation\XmlElement;

/**
 * @XmlNamespace(uri="http://www.w3.org/2005/Atom", prefix="atom")
 */
class User
{
    /**
    * @XmlElement(cdata=false, namespace="http://www.w3.org/2005/Atom")
    */
    private $id = 'my_id';
}

Resulting XML:

<atom:id>my_id</atom:id>

@XmlNamespace¶

This annotation allows you to specify Xml namespace/s and prefix used.

<?php

use JMS\Serializer\Annotation\XmlNamespace;

/**
 * @XmlNamespace(uri="http://example.com/namespace")
 * @XmlNamespace(uri="http://www.w3.org/2005/Atom", prefix="atom")
 */
class BlogPost
{
    /**
     * @Type("JMS\Serializer\Tests\Fixtures\Author")
     * @Groups({"post"})
     * @XmlElement(namespace="http://www.w3.org/2005/Atom")
     */
     private $author;
}

class Author
{
    /**
     * @Type("string")
     * @SerializedName("full_name")
     */
     private $name;
}

Resulting XML:

<?xml version="1.0" encoding="UTF-8"?>
<blog-post xmlns="http://example.com/namespace" xmlns:atom="http://www.w3.org/2005/Atom">
    <atom:author>
        <full_name><![CDATA[Foo Bar]]></full_name>
    </atom:author>
</blog>

/**
 * @VirtualProperty(
 *     "classlow",
 *     exp="object.getVirtualValue(1)",
 *     options={@Until("8")}
 * )
 * @VirtualProperty(
 *     "classhigh",
 *     exp="object.getVirtualValue(8)",
 *     options={@Since("6")}
 * )
 */
#[VirtualProperty('classlow', exp: 'object.getVirtualValue(1)', options: [[Until::class, ['8']]])]
#[VirtualProperty('classhigh', exp: 'object.getVirtualValue(8)', options: [[Since::class, ['6']]])]
class ObjectWithVersionedVirtualProperties
{
    /**
     * @Groups({"versions"})
     * @VirtualProperty
     * @SerializedName("low")
     * @Until("8")
     */
    #[Groups(['versions'])]
    #[VirtualProperty]
    #[SerializedName('low')]
    #[Until('8')]
    public function getVirtualLowValue()
    {
        return 1;
    }
...