Merge branch 'blaues0cke-custom-normalizer' into 2.0

Author: dunglas

core/content-negotiation.md

@@ -68,6 +68,107 @@ API Platform Core will automatically call the serializer with your defined forma
 as `format` parameter during the deserialization process. Then it will return the result to the client with the asked MIME
 type using its built-in responder.
 
+
+## Writing a Custom Normalizer
+
+Using composition is the recommended way to implement a custom normalizer. You can use the following template to start with your
+own implementation of `CustomItemNormalizer`:
+
+
+```yaml
+# app/config/services.yml
+
+services:
+    app.custom_item_normalizer:
+        public: false
+        class: AppBundle\Serializer\CustomItemNormalizer
+        arguments: [ '@api_platform.serializer.normalizer.item' ]
+        tags: [ { name: serializer.normalizer } ]
+```
+
+```php
+<?php
+
+// src/AppBundle/Serializer/CustomItemNormalizer.php
+
+namespace AppBundle\Serializer;
+
+use Symfony\Component\Serializer\Normalizer\DenormalizerInterface;
+use Symfony\Component\Serializer\Normalizer\NormalizerInterface;
+
+class CustomItemNormalizer implements NormalizerInterface, DenormalizerInterface
+{
+    private $normalizer;
+
+    public function __construct(NormalizerInterface $normalizer)
+    {
+        if (!$normalizer instanceof DenormalizerInterface) {
+            throw new \InvalidArgumentException('The normalizer must implement the DenormalizerInterface');
+        }
+
+        $this->normalizer = $normalizer;
+    }
+
+    public function denormalize($data, $class, $format = null, array $context = [])
+    {
+        return $this->normalizer->denormalize($data, $class, $format, $context);
+    }
+
+    public function supportsDenormalization($data, $type, $format = null)
+    {
+        return $this->normalizer->supportsDenormalization($data, $type, $format);
+    }
+
+    public function normalize($object, $format = null, array $context = [])
+    {
+        return $this->normalizer->normalize($object, $format, $context);
+    }
+
+    public function supportsNormalization($data, $format = null)
+    {
+        return $this->normalizer->supportsNormalization($data, $format);
+    }
+}
+```
+
+For example if you want to make the `csv` format to work for even complex entities with a lot of hierarchy, you have
+to flatten or remove too complex relations:
+
+```php
+<?php
+
+// src/AppBundle/Serializer/CustomItemNormalizer.php
+
+namespace AppBundle\Serializer;
+
+use Symfony\Component\Serializer\Normalizer\DenormalizerInterface;
+use Symfony\Component\Serializer\Normalizer\NormalizerInterface;
+
+class CustomItemNormalizer implements NormalizerInterface, DenormalizerInterface
+{
+    // ...
+
+    public function normalize($object, $format = null, array $context = [])
+    {
+        $result = $this->normalizer->normalize($object, $format, $context);
+
+        if ('csv' !== $format || !is_array($result)) {
+            return $result;
+        }
+
+        foreach ($result as $key => $value) {
+            if (is_array($value) && array_keys(array_keys($value)) === array_keys($value)) {
+                unset($result[$key]);
+            }
+        }
+
+        return $result;
+    }
+    
+    // ...
+}
+```
+
 Previous chapter: [The Event System](events.md)
 
 Next chapter: [Using External JSON-LD Vocabularies](external-vocabularies.md)

index.md

@@ -52,6 +52,7 @@
     1.  [Enabling Several Formats](core/content-negotiation.md#enabling-several-formats)
     2.  [Registering a Custom Serializer](core/content-negotiation.md#registering-a-custom-serializer)
     3.  [Creating a Responder](core/content-negotiation.md#creating-a-responder)
+    4.  [Writing a Custom Normalizer](core/content-negotiation.md#writing-a-custom-normalizer)
 11. [Using External JSON-LD Vocabularies](core/external-vocabularies.md)
 12. [Extending JSON-LD context](core/extending-jsonld-context.md)
 13. [Data Providers](core/data-providers.md)