Merge pull request #1287 from gam6itko/master

[DOCS] Add 'Deserialization Exclusion Strategy with Groups' topic
schmittjoh · Feb 21, 2021 · c5100ac · c5100ac
2 parents c089420 + f5f437e
commit c5100ac
Show file tree

Hide file tree

Showing 2 changed files with 123 additions and 0 deletions.
diff --git a/doc/cookbook/exclusion_strategies.rst b/doc/cookbook/exclusion_strategies.rst
@@ -224,6 +224,52 @@ This would result in the following json::
         ]
     }
 
+Deserialization Exclusion Strategy with Groups
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+You can use ``@Groups`` to cut off unwanted properties while deserialization.
+
+.. code-block:: php
+
+    use JMS\Serializer\Annotation\Groups;
+
+    class GroupsObject
+    {
+        /**
+         * @Groups({"foo"})
+         */
+        public $foo;
+
+        /**
+         * @Groups({"foo","bar"})
+         */
+        public $foobar;
+
+        /**
+         * @Groups({"bar", "Default"})
+         */
+        public $bar;
+
+        /**
+         * @Type("string")
+         */
+        public $none;
+    }
+
+.. code-block:: php
+
+    $data = [
+        'foo'    => 'foo',
+        'foobar' => 'foobar',
+        'bar'    => 'bar',
+        'none'   => 'none',
+    ];
+    $context = DeserializationContext::create()->setGroups(['foo']);
+    $object = $serializer->fromArray($data, GroupsObject::class, $context);
+    // $object->foo is 'foo'
+    // $object->foobar is 'foobar'
+    // $object->bar is null
+    // $object->none is null
+
 Limiting serialization depth of some properties
 -----------------------------------------------
 You can limit the depth of what will be serialized in a property with the

diff --git a/tests/Deserializer/BaseDeserializationTest.php b/tests/Deserializer/BaseDeserializationTest.php
@@ -0,0 +1,77 @@
+<?php
+
+declare(strict_types=1);
+
+namespace JMS\Serializer\Tests\Deserializer;
+
+use JMS\Serializer\DeserializationContext;
+use JMS\Serializer\SerializerBuilder;
+use JMS\Serializer\Tests\Fixtures\GroupsObject;
+use PHPUnit\Framework\TestCase;
+
+class BaseDeserializationTest extends TestCase
+{
+    /**
+     * @dataProvider dataDeserializerGroupExclusion
+     */
+    public function testDeserializerGroupExclusion(array $data, array $groups, array $expected): void
+    {
+        $serializer = SerializerBuilder::create()->build();
+        $context = DeserializationContext::create()->setGroups($groups);
+        $object = $serializer->fromArray($data, GroupsObject::class, $context);
+        self::assertSame($expected, $serializer->toArray($object));
+    }
+
+    public function dataDeserializerGroupExclusion(): iterable
+    {
+        $data = [
+            'foo'    => 'foo',
+            'foobar' => 'foobar',
+            'bar'    => 'bar',
+            'none'   => 'none',
+        ];
+
+        yield [
+            $data,
+            ['Default'],
+            [
+                'bar'  => 'bar',
+                'none' => 'none',
+            ],
+        ];
+
+        yield [
+            $data,
+            ['foo'],
+            [
+                'foo'    => 'foo',
+                'foobar' => 'foobar',
+            ],
+        ];
+
+        yield [
+            $data,
+            ['bar'],
+            [
+                'foobar' => 'foobar',
+                'bar'    => 'bar',
+            ],
+        ];
+
+        yield [
+            $data,
+            ['foo', 'bar'],
+            [
+                'foo'    => 'foo',
+                'foobar' => 'foobar',
+                'bar'    => 'bar',
+            ],
+        ];
+
+        yield [
+            $data,
+            ['you_shall_not_pass'],
+            [],
+        ];
+    }
+}