JMSSerializerBundle Documentation

When upgrading from 0.9 to 0.10:

• Custom Handlers: SerializationHandlerInterface and DeserializationHandlerInterface have been removed. Use the new handler system for specific types, or the event system for handling arbitrary/unknown types.
• Traversable Objects: Objects implementing Traversable are no longer treated specially and are serialized as regular objects. To restore previous behavior, use the @Type annotation to force serialization to an array:

/** @Type("array") */
private $myTraversableObject;

• Datetime Handlers: Most jms_serializer.handlers configuration is gone. You can still configure the built-in datetime handler, but it is recommended to specify the format directly via the @Type annotation:

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

When upgrading from version 1.x to 2.0, note the following breaking changes:

• Alias Change: The serializer alias has been removed. Use the jms_serializer alias instead.
• DateTime Format: The default datetime format has changed from ISO8601 (Y-m-d\TH:i:sO) to RFC3339 (Y-m-d\TH:i:sP).
• Metadata Configuration: Defining non-existent metadata directories will now trigger an exception. Additionally, the name attribute (or key) for metadata directory definitions is now mandatory.

After installation, you must register the bundle in your AppKernel.php file within the registerBundles() method.

// in AppKernel::registerBundles()
$bundles = array(
    // ...
    new JMS\SerializerBundle\JMSSerializerBundle(),
    // ...
);

To download the latest stable version of the bundle, run the following command in your project directory. This requires Composer to be installed on your system.

$ composer require jms/serializer-bundle

In version 3.0, defining naming strategies via parameters is no longer supported. You must now define the naming strategy under the jms_serializer.property_naming configuration key using the service ID.

# Before 3.0
parameters:
    jms_serializer.serialized_name_annotation_strategy.class: JMS\Serializer\Naming\IdenticalPropertyNamingStrategy

# After 3.0
jms_serializer:
    property_naming:
        id: 'jms_serializer.identical_property_naming_strategy' # service id of the naming strategy

For applications using the Symfony Standard structure, you must manually register the bundle in your Kernel by adding it to the registerBundles() method in app/AppKernel.php.

<?php
// app/AppKernel.php

// ...
class AppKernel extends Kernel
{
    public function registerBundles()
    {
        $bundles = array(
            // ...
            new JMS\SerializerBundle\JMSSerializerBundle(),
        );

        // ...
    }
}

You can extend the Expression Language used by the serializer by providing a custom function provider via the jms.expression.function_provider tag. Your provider must implement Symfony\Component\ExpressionLanguage\ExpressionFunctionProviderInterface and return an array of ExpressionFunction objects in its getFunctions() method.

use Symfony\Component\ExpressionLanguage\ExpressionFunction;
use Symfony\Component\ExpressionLanguage\ExpressionFunctionProviderInterface;

class MyFunctionProvider implements ExpressionFunctionProviderInterface
{
    public function getFunctions()
    {
        return [
            new ExpressionFunction('str_rot13', function ($arg) {
                return sprintf('str_rot13(%s)', $arg);
            }, function (array $variables, $value) {
                return str_rot13($value);
            })
        ];
    }
}

You can register custom handlers to manage specific types or formats during serialization or deserialization. Use the jms_serializer.handler or jms_serializer.subscribing_handler tags on your service.

If you omit the method attribute, the bundle will attempt to use a default naming convention: serializeTypeToFormat for serialization or deserializeTypeFromFormat for deserialization.

my_handler:
    class: MyHandler
    tags:
        - name: jms_serializer.handler
          type: DateTime
          direction: serialization
          format: json
          method: serializeDateTimeToJson

To hook into the serialization lifecycle, register listeners using the jms_serializer.event_listener or jms_serializer.event_subscriber tags.

Note: These are not standard Symfony kernel events; you cannot use kernel.event_listener or @DI\Observe annotations to catch these. You must use the specific JMS serializer tags.

Install the bundle using the Composer package manager by running the following command:

composer require jms/serializer-bundle