From 800017d4267596fc61b557a2eedae5832ea75089 Mon Sep 17 00:00:00 2001
From: Maxime Steinhausser <maxime.steinhausser@elao.com>
Date: Thu, 13 Oct 2022 14:50:18 +0200
Subject: [PATCH] [Serializer] Allow to provide (de)normalization context in
 mapping

---
 components/serializer.rst |   5 ++
 serializer.rst            | 106 ++++++++++++++++++++++++++++++++++++++
 2 files changed, 111 insertions(+)

diff --git a/components/serializer.rst b/components/serializer.rst
index 1690959defa..b6e5498d31b 100644
--- a/components/serializer.rst
+++ b/components/serializer.rst
@@ -229,6 +229,11 @@ normalized data, instead of the denormalizer re-creating them. Note that
 arrays of objects. Those will still be replaced when present in the normalized
 data.
 
+Context
+-------
+
+Many Serializer features can be configured :doc:`using a context </serializer#serializer-context>`.
+
 .. _component-serializer-attributes-groups:
 
 Attributes Groups
diff --git a/serializer.rst b/serializer.rst
index ab3e8b2002f..cc98e64e66e 100644
--- a/serializer.rst
+++ b/serializer.rst
@@ -172,6 +172,112 @@ configuration:
     The ability to configure the ``default_context`` option in the
     Serializer was introduced in Symfony 5.4.
 
+You can also specify the context on a per-property basis::
+
+.. configuration-block::
+
+    .. code-block:: php-annotations
+
+        namespace App\Model;
+
+        use Symfony\Component\Serializer\Annotation\Context;
+        use Symfony\Component\Serializer\Normalizer\DateTimeNormalizer;
+
+        class Person
+        {
+            /**
+             * @Context({ DateTimeNormalizer::FORMAT_KEY = 'Y-m-d' })
+             */
+            public $createdAt;
+
+            // ...
+        }
+
+    .. code-block:: php-attributes
+
+        namespace App\Model;
+
+        use Symfony\Component\Serializer\Annotation\Context;
+        use Symfony\Component\Serializer\Normalizer\DateTimeNormalizer;
+
+        class Person
+        {
+            #[Context([DateTimeNormalizer::FORMAT_KEY => 'Y-m-d'])]
+            public $createdAt;
+
+            // ...
+        }
+
+    .. code-block:: yaml
+
+        App\Model\Person:
+            attributes:
+                createdAt:
+                    context:
+                        datetime_format: 'Y-m-d'
+
+    .. code-block:: xml
+
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <serializer xmlns="http://symfony.com/schema/dic/serializer-mapping"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xsi:schemaLocation="http://symfony.com/schema/dic/serializer-mapping
+                https://symfony.com/schema/dic/serializer-mapping/serializer-mapping-1.0.xsd"
+        >
+            <class name="App\Model\Person">
+                <attribute name="createdAt">
+                    <context>
+                        <entry name="datetime_format">Y-m-d</entry>
+                    </context>
+                </attribute>
+            </class>
+        </serializer>
+
+Use the options to specify context specific to normalization or denormalization::
+
+    namespace App\Model;
+
+    use Symfony\Component\Serializer\Annotation\Context;
+    use Symfony\Component\Serializer\Normalizer\DateTimeNormalizer;
+
+    class Person
+    {
+        #[Context(
+            normalizationContext: [DateTimeNormalizer::FORMAT_KEY => 'Y-m-d'],
+            denormalizationContext: [DateTimeNormalizer::FORMAT_KEY => \DateTime::RFC3339],
+        )]
+        public $createdAt;
+
+        // ...
+    }
+
+You can also restrict the usage of a context to some groups::
+
+    namespace App\Model;
+
+    use Symfony\Component\Serializer\Annotation\Context;
+    use Symfony\Component\Serializer\Normalizer\DateTimeNormalizer;
+
+    class Person
+    {
+        #[Serializer\Groups(['extended'])]
+        #[Serializer\Context([DateTimeNormalizer::FORMAT_KEY => \DateTime::RFC3339])]
+        #[Serializer\Context(
+            context: [DateTimeNormalizer::FORMAT_KEY => \DateTime::RFC3339_EXTENDED],
+            groups: ['extended'],
+        )]
+        public $createdAt;
+
+        // ...
+    }
+
+The attribute/annotation can be repeated as much as needed on a single property.
+Context without group is always applied first. Then context for the matching groups are merged in the provided order.
+
+.. versionadded:: 5.3
+
+    The ``Context`` attribute, annotation and the configuration options were introduced in Symfony 5.3.
+
 .. _serializer-using-serialization-groups-annotations:
 
 Using Serialization Groups Annotations