From 97f48e5c1747766adbb80703c3d412dd59c28f6f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Dunglas?= Date: Thu, 6 Oct 2016 16:22:38 +0200 Subject: [PATCH 1/3] [Serializer] Docs for the @MaxDepth annotation --- components/serializer.rst | 91 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 91 insertions(+) diff --git a/components/serializer.rst b/components/serializer.rst index ba4a8189a5f..eaeaf680409 100644 --- a/components/serializer.rst +++ b/components/serializer.rst @@ -627,6 +627,97 @@ having unique identifiers:: var_dump($serializer->serialize($org, 'json')); // {"name":"Les-Tilleuls.coop","members":[{"name":"K\u00e9vin", organization: "Les-Tilleuls.coop"}]} +Handling Serialization Depth +---------------------------- + +The Serializer component is able to detect and limit the serialization depth. It is especially useful when +serializing large trees. Assume the following data structure:: + + namespace Acme; + + class MyObj + { + public $foo; + + /** + * @var self + */ + public $child; + } + + $level1 = new MyObj(); + $level1->foo = 'level1'; + + $level2 = new MyObj(); + $level2->foo = 'level2'; + $level1->child = $level2; + + $level3 = new MyObj(); + $level3->foo = 'level3'; + $level2->child = $level3; + +The serializer can be configured to set a maximum depth for a given property. Here, we set it to 2 for the ``$child`` +property: + +.. configuration-block:: + + .. code-block:: php-annotations + + use Symfony\Component\Serializer\Annotation\MaxDepth; + + namespace Acme; + + class MyObj + { + /** + * @MaxDepth(2) + */ + public $foo; + + // ... + } + + .. code-block:: yaml + + Acme\MyObj: + attributes: + foo: + max_depth: 2 + + .. code-block:: xml + + + + + + 2 + + + +The metadata loader corresponding to the chosen format must be configured in order to use this feature. +It is done automatically when using the Symfony Standard Edition. When using the standalone component, refer +to :ref:`the groups documentation ` to learn how to do that. + +The check is only done if the `enable_max_depth` key of the serializer context is set to ``true``. In the following +example, the third level is not serialized because it is deeper than the configured maximum depth (2). + + $result = $serializer->normalize($level1, null, array('enable_max_depth' => true)); + /* + $result = array( + 'foo' => 'level1', + 'child' => array( + 'foo' => 'level2', + 'child' => array( + 'child' => null, + ), + ), + ); + */ + Handling Arrays --------------- From 93dcc3f962f4a60a5dcd627e153bceea1c53a566 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Dunglas?= Date: Sat, 8 Oct 2016 14:21:09 +0200 Subject: [PATCH 2/3] Fix comments --- components/serializer.rst | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/components/serializer.rst b/components/serializer.rst index eaeaf680409..8210d0009c4 100644 --- a/components/serializer.rst +++ b/components/serializer.rst @@ -663,19 +663,19 @@ property: .. code-block:: php-annotations - use Symfony\Component\Serializer\Annotation\MaxDepth; + use Symfony\Component\Serializer\Annotation\MaxDepth; - namespace Acme; + namespace Acme; - class MyObj - { - /** - * @MaxDepth(2) - */ - public $foo; + class MyObj + { + /** + * @MaxDepth(2) + */ + public $foo; - // ... - } + // ... + } .. code-block:: yaml @@ -703,7 +703,7 @@ It is done automatically when using the Symfony Standard Edition. When using the to :ref:`the groups documentation ` to learn how to do that. The check is only done if the `enable_max_depth` key of the serializer context is set to ``true``. In the following -example, the third level is not serialized because it is deeper than the configured maximum depth (2). +example, the third level is not serialized because it is deeper than the configured maximum depth (2):: $result = $serializer->normalize($level1, null, array('enable_max_depth' => true)); /* From d7395d3352ef62d8b22cb840c7550cf4d482d224 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Tue, 22 Nov 2016 09:41:52 +0100 Subject: [PATCH 3/3] Make lines shorter to comply with our soft limit of 80 chars per line --- components/serializer.rst | 22 +++++++++++++--------- 1 file changed, 13 insertions(+), 9 deletions(-) diff --git a/components/serializer.rst b/components/serializer.rst index 8210d0009c4..b0e80a680a0 100644 --- a/components/serializer.rst +++ b/components/serializer.rst @@ -630,8 +630,9 @@ having unique identifiers:: Handling Serialization Depth ---------------------------- -The Serializer component is able to detect and limit the serialization depth. It is especially useful when -serializing large trees. Assume the following data structure:: +The Serializer component is able to detect and limit the serialization depth. +It is especially useful when serializing large trees. Assume the following data +structure:: namespace Acme; @@ -656,8 +657,8 @@ serializing large trees. Assume the following data structure:: $level3->foo = 'level3'; $level2->child = $level3; -The serializer can be configured to set a maximum depth for a given property. Here, we set it to 2 for the ``$child`` -property: +The serializer can be configured to set a maximum depth for a given property. +Here, we set it to 2 for the ``$child`` property: .. configuration-block:: @@ -698,12 +699,15 @@ property: -The metadata loader corresponding to the chosen format must be configured in order to use this feature. -It is done automatically when using the Symfony Standard Edition. When using the standalone component, refer -to :ref:`the groups documentation ` to learn how to do that. +The metadata loader corresponding to the chosen format must be configured in +order to use this feature. It is done automatically when using the Symfony +Standard Edition. When using the standalone component, refer to +:ref:`the groups documentation ` to +learn how to do that. -The check is only done if the `enable_max_depth` key of the serializer context is set to ``true``. In the following -example, the third level is not serialized because it is deeper than the configured maximum depth (2):: +The check is only done if the ``enable_max_depth`` key of the serializer context +is set to ``true``. In the following example, the third level is not serialized +because it is deeper than the configured maximum depth of 2:: $result = $serializer->normalize($level1, null, array('enable_max_depth' => true)); /*