Add docs for data persisters

Author: dunglas

core/data-persisters.md

@@ -0,0 +1,68 @@
+# Data Persisters
+
+To mutate the application states during `POST`, `PUT`, `PATCH` or `DELETE` [operations](operations.md), API Platform calls
+classes called **data persisters**. Data persisters receive an instance of the class marked as an API resource (usually using
+the `@ApiResource` annotation). This instance has been created using data submitted by the client during [the deserialization
+process](serialization.md).
+
+A data persister using [Doctrine ORM](http://www.doctrine-project.org/projects/orm.html) is included with the library and
+is enabled by default. It is able to persist and delete objects that are also mapped as [Doctrine entities](https://www.doctrine-project.org/projects/doctrine-orm/en/2.6/reference/basic-mapping.html).
+
+However, you may want to store data to other persistence layers (ElasticSearch or MongoDB), to separate the public model
+of the API and the internal model mapped with the database; or to use patterns such as [CQRS](https://martinfowler.com/bliki/CQRS.html)
+to use a separate model for [read operations](data-providers.md) and for updates.
+
+Custom data persisters can be used to do so. A project can include as many data persisters as it needs. The first able to
+persist data for a given resource will be used.
+
+## Creating a Custom Data Persister
+
+To create a data persister, you have to implement the [`DataPersisterInterface`](https://github.com/api-platform/core/blob/master/src/DataPersister/DataPersisterInterface.php).
+This interface defines only 3 methods:
+
+* `persist`: to create or update the given data
+* `delete`: to delete the given data
+* `support`: to tell if the given data xcan be handled by this specific data persister
+
+Here is an example implementation:
+
+```php
+namespace App\DataPersister;
+
+use ApiPlatform\Core\DataPersister\DataPersisterInterface;
+use App\Entity\BlogPost;
+
+final class BlogPostDataPersister implements DataPersisterInterface
+{
+    public function supports($data): bool
+    {
+        return $data instanceof BlogPost;
+    }
+    
+    public function persist($data)
+    {
+      // call your persistence layer to save $data
+      return $data;
+    }
+    
+    public function delete($data): void
+    {
+      // call your persistence layer to delete $data
+    }
+}
+```
+
+If service autowiring and autoconfiguration are enabled (it's the case by default), you are done!
+
+Otherwise, if you use a custom dependency injection configuration, you need to register the corresponding service and add the
+`api_platform.data_persister` tag to it. As for collection data providers, the `priority` attribute can be used to order
+providers.
+
+```yaml
+# api/config/services.yaml
+services:
+    # ...
+    'App\DataPersister\BlogPostDataPersister': ~
+        # Uncomment only if autoconfiguration is disabled
+        #tags: [ 'api_platform.data_persister' ]
+```

core/data-providers.md

@@ -58,7 +58,8 @@ final class BlogPostCollectionDataProvider implements CollectionDataProviderInte
 }
 ```
 
-Then declare a Symfony service, for example:
+If you use the default configuration, the corresponding service will be automatically registered thanks to the [autowiring](https://symfony.com/doc/current/service_container/autowiring.html).
+To declare the service explicitly, or to set a custom priority, you can use the following snippet:
 
 ```yaml
 # api/config/services.yaml

index.md

@@ -81,11 +81,12 @@
     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)
-16. [Extensions](core/extensions.md)
+16. [Data Persisters](core/data-persisters.md)
+17. [Extensions](core/extensions.md)
     1.  [Custom Extension](core/extensions.md#custom-extension)
     2.  [Filter upon the current user](core/extensions.md#example)
-17. [Security](core/security.md)
-18. [Performance](core/performance.md)
+18. [Security](core/security.md)
+19. [Performance](core/performance.md)
     1.  [Enabling the Built-in HTTP Cache Invalidation System](core/performance.md#enabling-the-builtin-http-cache-invalidation-system)
     2.  [Enabling the Metadata Cache](core/performance.md#enabling-the-metadata-cache)
     3.  [Using PPM (PHP-PM)](core/performance.md#using-ppm-php-pm)
@@ -97,32 +98,32 @@
             3.  [Override at Resource and Operation Level](core/performance.md#override-at-resource-and-operation-level)
             4.  [Disable Eager Loading](core/performance.md#disable-eager-loading)
         3.  [Partial Pagination](core/performance.md#partial-pagination)
-19. [Operation Path Naming](core/operation-path-naming.md)
+20. [Operation Path Naming](core/operation-path-naming.md)
     1.  [Configuration](core/operation-path-naming.md#configuration)
     2.  [Create a Custom Operation Path Naming](core/operation-path-naming.md#create-a-custom-operation-path-resolver)
         1.  [Defining the Operation Path Naming](core/operation-path-naming.md#defining-the-operation-path-resolver)
         2.  [Registering the Service](core/operation-path-naming.md#registering-the-service)
         3.  [Configure it](core/operation-path-naming.md#configure-it)
-20. [Accept application/x-www-form-urlencoded Form Data](core/form-data.md)
-21. [FOSUserBundle Integration](core/fosuser-bundle.md)
+21. [Accept application/x-www-form-urlencoded Form Data](core/form-data.md)
+22. [FOSUserBundle Integration](core/fosuser-bundle.md)
     1.  [Installing the Bundle](core/fosuser-bundle.md#installing-the-bundle)
     2.  [Enabling the Bridge](core/fosuser-bundle.md#enabling-the-bridge)
     3.  [Creating a `User` Entity with Serialization Groups](core/fosuser-bundle.md#creating-a-user-entity-with-serialization-groups)
-22. [Adding a JWT authentication using LexikJWTAuthenticationBundle](core/jwt.md)
+23. [Adding a JWT authentication using LexikJWTAuthenticationBundle](core/jwt.md)
     1. [Testing with Swagger](core/jwt.md#testing-with-swagger)
     2. [Testing with Behat](core/jwt.md#testing-with-behat)
-23. [NelmioApiDocBundle integration](core/nelmio-api-doc.md)
-24. [AngularJS Integration](core/angularjs-integration.md)
+24. [NelmioApiDocBundle integration](core/nelmio-api-doc.md)
+25. [AngularJS Integration](core/angularjs-integration.md)
     1.  [Restangular](core/angularjs-integration.md#restangular)
     2.  [ng-admin](core/angularjs-integration.md#ng-admin)
-25. [Swagger Support](core/swagger.md)
+26. [Swagger Support](core/swagger.md)
     1. [Override Swagger documentation](core/swagger.md#override-swagger-documentation)
-26. [GraphQL Support](core/graphql.md)
+27. [GraphQL Support](core/graphql.md)
     1. [Overall View](core/graphql.md#overall-view)
     2. [Enabling GraphQL](core/graphql.md#enabling-graphql)
     3. [GraphiQL](core/graphql.md#graphiql)
-27. [Handling Data Transfer Objects (DTOs)](core/dto.md)
-28. [Handling File Upload with VichUploaderBundle](core/file-upload.md)
+28. [Handling Data Transfer Objects (DTOs)](core/dto.md)
+29. [Handling File Upload with VichUploaderBundle](core/file-upload.md)
 
 ## The Schema Generator Component: Generate Data Models from Open Vocabularies