From 752873efc856b0743d9d898351a56d5a9fb40441 Mon Sep 17 00:00:00 2001 From: Asmir Mustafic Date: Mon, 14 Jan 2019 07:43:27 +0100 Subject: [PATCH] document expression language providers --- Resources/doc/configuration.rst | 458 ++++++++++++++++++-------------- 1 file changed, 253 insertions(+), 205 deletions(-) diff --git a/Resources/doc/configuration.rst b/Resources/doc/configuration.rst index b77287d0..8a2c1b1f 100644 --- a/Resources/doc/configuration.rst +++ b/Resources/doc/configuration.rst @@ -1,205 +1,253 @@ -Configuration -============= - -Handlers --------- -You can register any service as a handler by adding either the ``jms_serializer.handler``, -or the ``jms_serializer.subscribing_handler``. - -.. code-block :: xml - - - - - -.. 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. - -Defining Metadata ------------------ -To define the metadata using YAML or XML, you need to specify their location and to which PHP namespace prefix they refer. - -.. configuration-block :: - - .. code-block :: yaml - - jms_serializer: - metadata: - directories: - App: - namespace_prefix: "App\\Entity" - path: "%kernel.root_dir%/serializer/app" - FOSUB: - namespace_prefix: "FOS\\UserBundle" - path: "%kernel.root_dir%/serializer/FOSUB" - - .. code-block :: xml - - - - - - - - -.. note :: - - - ``path`` must not contain trailing slashes - - If you are using YAML files as metadata format, the file extension to use is ``.yml`` - - -Suppose you want to define the metadata using YAML for the classes in the ``App\\Entity`` namespace prefix -and the configured path is ``%kernel.root_dir%/serializer/app``, then your metadata file should be named: -``%kernel.root_dir%/serializer/app/Product.yml``. - - -This feature is also useful for **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. - - -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: - -.. configuration-block :: - - .. code-block :: yaml - - services: - jms_serializer.object_constructor: - alias: jms_serializer.doctrine_object_constructor - public: false - - .. code-block :: xml - - - - - - -Extension Reference -------------------- - -Below you find a reference of all configuration options with their default -values: - -.. configuration-block :: - - .. code-block :: yaml - - # config.yml - jms_serializer: - handlers: - datetime: - default_format: "Y-m-d\\TH:i:sP" # ATOM - default_timezone: "UTC" # defaults to whatever timezone set in php.ini or via date_default_timezone_set - array_collection: - initialize_excluded: false - - subscribers: - doctrine_proxy: - initialize_virtual_types: false - initialize_excluded: false - - object_constructors: - doctrine: - fallback_strategy: "null" # possible values ("null" | "exception" | "fallback") - - property_naming: - id: ~ - separator: _ - lower_case: 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" - warmup: - # list of directories to scan searching for php classes to use when warming up the cache - paths: - included: [] - excluded: [] - - 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_serialization: - options: 0 # json_encode options bitmask, suggested JSON_PRETTY_PRINT in development - depth: 512 - json_deserialization: - options: 0 # json_encode options bitmask, suggested JSON_PRETTY_PRINT in development - xml_serialization: - format_output: false - version: "1.0" - encoding: "UTF-8" - default_root_name: "result" - default_root_ns: null - xml_deserialization: - external_entities: false - doctype_whitelist: - - '' # an authorized document type for xml deserialization +Configuration +============= + +Handlers +-------- +You can register any service as a handler by adding either the ``jms_serializer.handler``, +or the ``jms_serializer.subscribing_handler``. + +.. code-block :: xml + + + + + +.. 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. + +Expression Language +------------------- + +You can add custom expression functions using the `jms.expression.function_provider` tag. + +.. configuration-block :: + + .. code-block :: xml + + + + + + .. code-block :: yaml + + my_function_provider: + class: MyFunctionProvider + tags: + - jms.expression.function_provider + + +A functions provider for the Symfony Expression Language might look something as this: + +.. code-block :: php + + 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 read more about it on the official `expression function providers`_ documentation. + +Defining Metadata +----------------- +To define the metadata using YAML or XML, you need to specify their location and to which PHP namespace prefix they refer. + +.. configuration-block :: + + .. code-block :: yaml + + jms_serializer: + metadata: + directories: + App: + namespace_prefix: "App\\Entity" + path: "%kernel.root_dir%/serializer/app" + FOSUB: + namespace_prefix: "FOS\\UserBundle" + path: "%kernel.root_dir%/serializer/FOSUB" + + .. code-block :: xml + + + + + + + + +.. note :: + + - ``path`` must not contain trailing slashes + - If you are using YAML files as metadata format, the file extension to use is ``.yml`` + + +Suppose you want to define the metadata using YAML for the classes in the ``App\\Entity`` namespace prefix +and the configured path is ``%kernel.root_dir%/serializer/app``, then your metadata file should be named: +``%kernel.root_dir%/serializer/app/Product.yml``. + + +This feature is also useful for **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. + + +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: + +.. configuration-block :: + + .. code-block :: yaml + + services: + jms_serializer.object_constructor: + alias: jms_serializer.doctrine_object_constructor + public: false + + .. code-block :: xml + + + + + + +Extension Reference +------------------- + +Below you find a reference of all configuration options with their default +values: + +.. configuration-block :: + + .. code-block :: yaml + + # config.yml + jms_serializer: + handlers: + datetime: + default_format: "Y-m-d\\TH:i:sP" # ATOM + default_timezone: "UTC" # defaults to whatever timezone set in php.ini or via date_default_timezone_set + array_collection: + initialize_excluded: false + + subscribers: + doctrine_proxy: + initialize_virtual_types: false + initialize_excluded: false + + object_constructors: + doctrine: + fallback_strategy: "null" # possible values ("null" | "exception" | "fallback") + + property_naming: + id: ~ + separator: _ + lower_case: 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" + warmup: + # list of directories to scan searching for php classes to use when warming up the cache + paths: + included: [] + excluded: [] + + 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_serialization: + options: 0 # json_encode options bitmask, suggested JSON_PRETTY_PRINT in development + depth: 512 + json_deserialization: + options: 0 # json_encode options bitmask, suggested JSON_PRETTY_PRINT in development + xml_serialization: + format_output: false + version: "1.0" + encoding: "UTF-8" + default_root_name: "result" + default_root_ns: null + xml_deserialization: + external_entities: false + doctype_whitelist: + - '' # an authorized document type for xml deserialization + + +.. _expression function providers: https://symfony.com/doc/current/components/expression_language/extending.html#using-expression-providers