jms/serializer Documentation

The jms/serializer library is a PHP tool designed to (de-)serialize data of any complexity. It is primarily used for converting complex PHP objects into formats like XML and JSON, and vice versa.

Key capabilities include:

• Handling circular references and complex exclusion strategies.
• Support for built-in PHP types such as dates and intervals.
• Integration with Doctrine ORM.
• Support for versioning (useful for API evolution).
• Configuration via XML, YAML, or PHP Annotations.

The jms/serializer library is designed to (de-)serialize complex data structures. Key capabilities include:

• Format Support: Currently supports XML and JSON.
• Complexity Handling: Handles circular references gracefully.
• Type Support: Includes built-in support for many PHP types, such as dates.
• Integrations: Integrates with Doctrine ORM and other tools.
• API Versioning: Supports versioning for API stability.
• Configuration: Can be configured using XML, YAML, or Doctrine Annotations.

Discriminators allow the serializer to determine the correct class to instantiate during deserialization based on a specific field value. You can configure this at the class level or via a union_discriminator on a property.

Class-level discriminator options:

• field_name: The property used to determine the type.
• map: A mapping of values to FQCNs.
• groups: The serialization groups this discriminator applies to.
• xml_attribute: Whether to use an XML attribute for the discriminator.
• xml_element: Configuration for the XML element representation.

Vendor\MyBundle\Model\ClassName:
    discriminator:
        field_name: type
        disabled: false
        map:
            some-value: ClassName
        groups: [foo, bar]
        xml_attribute: true
        xml_element:
            cdata: false
            namespace: http://www.w3.org/2005/Atom

JMS Serializer supports PHP 8 attributes. Note the following requirements and caveats:

• Optional Dependency: Starting from release 3.30.0, doctrine/annotations is an optional package. If you wish to continue using docblock annotations, you must explicitly require it in your composer.json.
• Nested Attributes: Due to PHP limitations with nested attributes, some syntax (like VirtualProperty options) has changed.
• Groups Edge Case: When using #[Groups], if you have a single item in the array where the key is value, the attribute may not work as expected. Use the named argument syntax instead: #[Groups(groups: ['value' => 'any value here'])].
• Unions: The system automatically resolves unions of primitive types. For classes containing union attributes, you must use the #[UnionDiscriminator] attribute to specify the type.

Virtual properties are properties that do not exist as physical fields on the class but are generated during serialization. You can define them in two ways:

1. Via Getter: Map a virtual property to an existing getter method.
2. Via Expression: Use an expression to compute the value.

Both types support name, serialized_name, and type configuration.

Vendor\MyBundle\Model\ClassName:
    virtual_properties:
        getSomeProperty:
            name: optional-prop-name
            serialized_name: foo
            type: integer
        expression_prop:
            name: optional-prop-name
            exp: object.getName()
            serialized_name: foo
            type: integer

When using stdClass objects, the following operations are not possible:

• Changing the serialization order of properties.
• Applying per-property exclusion policies.
• Specifying extra serialization metadata for properties (e.g., serialization name, type, or XML structure).
• Deserializing data back into stdClass objects.

The #[VirtualProperty] attribute allows you to treat method return values as if they were object properties during serialization.

Key behaviors:

• Method-level: Define it on a getter method. If no name is provided, it defaults to the method name with the get prefix removed.
• Class-level: Define it on a class to expose data using Symfony Expression Language via the exp option.
• Limitations: This only affects serialization; it is completely ignored during deserialization.
• PHP 8 Nested Attributes: Because PHP 8 lacks support for nested attributes, you must pass additional attributes (like SerializedName) inside the options array as an array containing the class name and an array of constructor arguments: [[ClassName::class, [args]]].

For standalone projects, use the JMS\Serializer\SerializerBuilder to create a serializer instance. Once built, you can use the serialize method, specifying the format (e.g., 'json') and the data you wish to convert.

$serializer = JMS\Serializer\SerializerBuilder::create()->build();
$jsonContent = $serializer->serialize($data, 'json');
echo $jsonContent; // or return it in a Response

Upgrading from 2.x to 3.x requires minimal effort.

Key Changes:

• The "deeper branch group exclusion strategy" introduced in 2.0.0 has been reverted to the behavior used in 1.x. If you were relying on this specific feature, you may need to adjust your configuration.
• Deprecations introduced in 2.x remain in 3.0.0 and will likely be removed in the next major version.

You can add versioning support to your objects to control property visibility based on a version number. This is useful for maintaining API compatibility.

• @Since("version"): The property is only serialized if the version is greater than or equal to the specified version.
• @Until("version"): The property is only serialized if the version is less than the specified version.

Both annotations accept a standardized PHP version number. To use versioning, create a SerializationContext and set the version using setVersion().