Add documentation about SerializerAwareDataProviderInterface (#336)

Author: vincentchalamon

core/data-providers.md

@@ -125,6 +125,45 @@ services:
         tags: [ 'api_platform.item_data_provider' ]
 ```
 
+## Injecting the Serializer in an `ItemDataProvider`
+
+In some cases, you may need to inject the `Serializer` in your `DataProvider`. There are no issues with the
+`CollectionDataProvider`, but when injecting it in the `ItemDataProvider` it will throw a `CircularReferenceException`.
+
+For this reason, we implemented the `SerializerAwareDataProviderInterface`:
+
+```php
+<?php
+// src/AppBundle/DataProvider/BlogPostItemDataProvider.php
+
+namespace AppBundle\DataProvider;
+
+use ApiPlatform\Core\DataProvider\ItemDataProviderInterface;
+use ApiPlatform\Core\DataProvider\SerializerAwareDataProviderInterface;
+use ApiPlatform\Core\DataProvider\SerializerAwareDataProviderTrait;
+use ApiPlatform\Core\Exception\ResourceClassNotSupportedException;
+use AppBundle\Entity\BlogPost;
+
+final class BlogPostItemDataProvider implements ItemDataProviderInterface, SerializerAwareDataProviderInterface
+{
+    use SerializerAwareDataProviderTrait;
+
+    public function supports(string $resourceClass, string $operationName = null): bool
+    {
+        return BlogPost::class === $resourceClass;
+    }
+
+    public function getItem(string $resourceClass, $id, string $operationName = null, array $context = []): ?BlogPost
+    {
+        // Retrieve data from anywhere you want, in a custom format
+        $data = '...';
+
+        // Deserialize data using the Serializer
+        return $this->getSerializer()->deserialize($data, BlogPost::class, 'custom');
+    }
+}
+```
+
 Previous chapter: [Extending JSON-LD context](extending-jsonld-context.md)
 
 Next chapter: [Extensions](extensions.md)

index.md

@@ -64,8 +64,9 @@
 12. [Using External JSON-LD Vocabularies](core/external-vocabularies.md)
 13. [Extending JSON-LD context](core/extending-jsonld-context.md)
 14. [Data Providers](core/data-providers.md)
-    1.  [Custom Collection Data Provider](core/data-providers.md#creating-a-custom-data-provider#custom-collection-data-provider)
-    2.  [Custom Item Data Provider](core/data-providers.md#returning-a-paged-collection#custom-item-data-provider)
+    1.  [Custom Collection Data Provider](core/data-providers.md#custom-collection-data-provider)
+    2.  [Custom Item Data Provider](core/data-providers.md#custom-item-data-provider)
+    3.  [Injecting the Serializer in an `ItemDataProvider`](core/data-providers.md#injecting-the-serializer-in-an-itemdataprovider)
 15. [Extensions](core/extensions.md)
     1.  [Custom Extension](core/extensions.md#custom-extension)
     2.  [Filter upon the current user](core/extensions.md#example)