Johannes Schmitt

Versions

Table Of Contents

Support

You can obtain free community support for example through stackoverflow, or also through the Symfony2 mailing list.

If you think you found a bug, please create a ticket in the bug tracker.

Continuous Inspections

If you take code quality seriously, try out the new continuous inspection service.
scrutinizer-ci.com

GitHub

Configuration

Handlers

You can register any service as a handler by adding either the jms_serializer.handler, or the jms_serializer.subscribing_handler.

<service id="my_handler" class="MyHandler">
    <tag name="jms_serializer.handler" type="DateTime" direction="serialization" format="json"
                method="serializeDateTimeToJson" />
</service>
Tip: The direction attribute is not required if you want to support both directions. Likewise can the method attribute be omitted, then a default using the scheme serializeTypeToFormat, or deserializeTypeFromFormat will be used for serialization or deserialization respectively.

Event Dispatcher

You can use the tags jms_serializer.event_listener, or jms_serializer.event_subscriber in order to register a listener.

The semantics are mainly the same as registering a regular Symfony2 event listener except that you can specify some additional attributes:

  • format: The format that you want to listen to; defaults to all formats.
  • class: The type name that you want to listen to; defaults to all types.
  • direction: The direction (serialization, or deserialization); defaults to both.
Note: Events are not dispatched by Symfony2?s event dispatcher as such you cannot register listeners with the kernel.event_listener tag, or the @DI\Observe annotation. Please see above.

Overriding Third-Party Metadata

Sometimes you want to serialize objects which are shipped by a third-party bundle. Such a third-party bundle might not ship with metadata that suits your needs, or possibly none, at all. In such a case, you can override the default location that is searched for metadata with a path that is under your control.

jms_serializer:
    metadata:
        directories:
            FOSUB:
                namespace_prefix: "FOS\\UserBundle"
                path: "%kernel.root_dir%/serializer/FOSUB"

<jms-serializer>
    <metadata>
        <directory namespace_prefix="FOS\UserBundle"
                   path="%kernel.root_dir%/serializer/FOSUB" />
    </metadata>
</jms-serializer>

Changing the Object Constructor

A Constructor class is used to construct new objects during deserialization. The default constructor uses the unserialize function to construct objects. Other constructors are configured as services. You can set the constructor by changing the service alias:

    Extension Reference

    Below you find a reference of all configuration options with their default values:

    # config.yml
jms_serializer:
    enable_short_alias: true # controls if "serializer" service is aliased to jms_serializer.serializer service
    handlers:
        datetime:
            default_format: "c" # ISO8601
            default_timezone: "UTC" # defaults to whatever timezone set in php.ini or via date_default_timezone_set
        array_collection:
            initialize_excluded: true # suggested false for better performance

    subscribers:
        doctrine_proxy:
            initialize_virtual_types: true # suggested false for better performance
            initialize_excluded: true # suggested false for better performance

    object_constructors:
        doctrine:
            fallback_strategy: "null" # possible values ("null" | "exception" | "fallback")

    property_naming:
        id: ~
        separator:  _
        lower_case: true
        enable_cache: true

    metadata:
        cache: file
        debug: "%kernel.debug%"
        file_cache:
            dir: "%kernel.cache_dir%/serializer"

        # Using auto-detection, the mapping files for each bundle will be
        # expected in the Resources/config/serializer directory.
        #
        # Example:
        # class: My\FooBundle\Entity\User
        # expected path: @MyFooBundle/Resources/config/serializer/Entity.User.(yml|xml|php)
        auto_detection: true

        # if you don't want to use auto-detection, you can also define the
        # namespace prefix and the corresponding directory explicitly
        directories:
            any-name:
                namespace_prefix: "My\\FooBundle"
                path: "@MyFooBundle/Resources/config/serializer"
            another-name:
                namespace_prefix: "My\\BarBundle"
                path: "@MyBarBundle/Resources/config/serializer"

    expression_evaluator:
        id: jms_serializer.expression_evaluator # auto detected

    default_context:
        serialization:
            serialize_null: false
            version: ~
            attributes: {}
            groups: ['Default']
            enable_max_depth_checks: false
        deserialization:
            serialize_null: false
            version: ~
            attributes: {}
            groups: ['Default']
            enable_max_depth_checks: false

    visitors:
        json:
            options: 0 # json_encode options bitmask, suggested JSON_PRETTY_PRINT in development
        xml:
            doctype_whitelist:
                - '<!DOCTYPE authorized SYSTEM "http://some_url">' # an authorized document type for xml deserialization
            format_output: true # suggested false in production

    <!-- config.xml -->
<jms-serializer>
    <handlers>
        <object-based />
        <datetime
            format="Y-mdTH:i:s"
            default-timezone="UTC" />
        <array-collection />
        <form-error />
        <constraint-violation />
    </handlers>

    <property-naming
        seperator="_"
        lower-case="true" />

    <metadata
        cache="file"
        debug="%kernel.debug%"
        auto-detection="true">

        <file-cache dir="%kernel.cache_dir%/serializer" />

        <!-- If auto-detection is enabled, mapping files for each bundle will
             be expected in the Resources/config/serializer directory.

             Example:
             class: My\FooBundle\Entity\User
             expected path: @MyFooBundle/Resources/config/serializer/Entity.User.(yml|xml|php)
        -->
        <directory
            namespace-prefix="My\FooBundle"
            path="@MyFooBundle/Resources/config/serializer" />
    </metadata>

    <visitors>
        <xml>
            <whitelisted-doctype><![CDATA[<!DOCTYPE...>]]></whitelisted-doctype>
            <whitelisted-doctype><![CDATA[<!DOCTYPE...>]]></whitelisted-doctype>
        </xml>
    </visitors>
</jms-serializer>