Merge branch '2.2'

Author: dunglas

core/data-persisters.md

@@ -0,0 +1,69 @@
+# Data Persisters
+
+To mutate the application states during `POST`, `PUT`, `PATCH` or `DELETE` [operations](operations.md), API Platform uses
+classes called **data persisters**. Data persisters receive an instance of the class marked as an API resource (usually using
+the `@ApiResource` annotation). This instance contains 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, MongoDB, external web services...)
+* not publicly expose the internal model mapped with the database through the API
+* use a separate model for [read operations](data-providers.md) and for updates by implementing patterns such as [CQRS](https://martinfowler.com/bliki/CQRS.html)
+
+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`: checks whether the given data is supported by this data persister
+
+Here is an implementation example:
+
+```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 (they are 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. The `priority` attribute can be used to order persisters.
+
+```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 [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

core/design.md

@@ -0,0 +1,50 @@
+# General Design Considerations
+
+Since you only need to describe the structure of the data to expose, API Platform is both [a "design-first" and "code-first"](https://swagger.io/blog/api-design/design-first-or-code-first-api-development/)
+API framework. However, the "design-first" methodology is strongly recommended: first you design the **public shape** of
+API endpoints.
+
+To do so, you have to write a plain old PHP object representing the input and output of your endpoint. This is the class
+that is [marked with the `@ApiResource` annotation](../distribution/index.md).
+This class **doesn't have** to be mapped with Doctrine ORM, or any other persistence system. It must be simple (it's usually
+just a data structure with no or minimal behaviors) and will be automatically converted to [Hydra](extending-jsonld-context.md),
+[OpenAPI / Swagger](swagger.md) and [GraphQL](graphql.md) documentations or schemas by API Platform (there is a 1-1 mapping
+between this class and those docs).
+
+Then, it's up to the developer to feed API Platform with an hydrated instance of this API resource object by implementing
+the [`DataProviderInterface`](data-providers.md). Basically, the data provider will query the persistence system (RDBMS,
+document or graph DB, external API...), and must hydrate and return the POPO that has been designed as mentioned above.
+
+When updating a state (`POST`, `PUT`, `PATCH`, `DELETE` HTTP methods), it's up to the developer to properly persist the
+data provided by API Platform's resource object [hydrated by the serializer](serialization.md).
+To do so, there is another interface to implement: [`DataPersisterInterface`](data-persisters.md).
+
+This class will read the API resource object (the one marked with `@ApiResource`) and:
+ 
+* persist it directly in the database;
+* or hydrate a DTO then trigger a command;
+* or populate an event store;
+* or persist the data in any other useful way.
+
+The logic of data persisters is the responsibility of application developers, and is **out of the API Platform's scope**.
+
+For [Rapid Application Development](https://en.wikipedia.org/wiki/Rapid_application_development), convenience and prototyping,
+**if and only if the class marked with `@ApiResource` is also a Doctrine entity**, the developer can use the Doctrine
+ORM's data provider and persister implementations shipped with API Platform.
+
+In this case, the public (`@ApiResource`) and internal (Doctrine entity) data model are shared. Then, API Platform will
+be able to query, filter, paginate and persist automatically data.
+This is approach is super-convenient and efficient, but is probably **not a good idea** for non-[CRUD](https://en.wikipedia.org/wiki/Create,_read,_update_and_delete)
+and/or large systems.
+Again, it's up to the developers to use, or to not use those built-in data providers/persisters depending of the business
+they are dealing with. API Platform makes it easy to create custom data providers and persisters, and to implement appropriate
+patterns such as [CQS](https://www.martinfowler.com/bliki/CommandQuerySeparation.html) or [CQRS](https://martinfowler.com/bliki/CQRS.html).
+
+Last but not least, to create [Event Sourcing](https://martinfowler.com/eaaDev/EventSourcing.html)-based systems, a convenient
+approach is:
+
+* to persist data in an event store using a custom [data persister](data-persisters.md)
+* to create projections in standard RDBMS (Postgres, MariaDB...) tables or views
+* to map those projections with read-only Doctrine entity classes **and** to mark those classes with `@ApiResource`
+
+You can then benefit from the built-in Doctrine filters, sorting, pagination, auto-joins, etc provided by API Platform.

core/events.md

@@ -76,10 +76,10 @@ Built-in event listeners are:
 Name                          | Event              | Pre & Post hooks                     | Priority | Description
 ------------------------------|--------------------|--------------------------------------|----------|--------------------------------------------------------------------------------------------------------------------------
 `AddFormatListener`           | `kernel.request`   | None                                 | 7        | guess the best response format ([content negotiation](content-negotiation.md))
-`ReadListener`                | `kernel.request`   | `PRE_READ`, `POST_READ`              | 4        | retrieve data from the persistence system using the [data providers](data-providers.md)
+`ReadListener`                | `kernel.request`   | `PRE_READ`, `POST_READ`              | 4        | retrieve data from the persistence system using the [data providers](data-providers.md) (`GET`, `PUT`, `DELETE`)
 `DeserializeListener`         | `kernel.request`   | `PRE_DESERIALIZE`, `POST_DESERIALIZE`| 2        | deserialize data into a PHP entity (`GET`, `POST`, `DELETE`); update the entity retrieved using the data provider (`PUT`)
 `ValidateListener`            | `kernel.view`      | `PRE_VALIDATE`, `POST_VALIDATE`      | 64       | [validate data](validation.md) (`POST`, `PUT`)
-`WriteListener`               | `kernel.view`      | `PRE_WRITE`, `POST_WRITE`            | 32       | if using the Doctrine ORM, persist data (`POST`, `PUT`, `DELETE`)
+`WriteListener`               | `kernel.view`      | `PRE_WRITE`, `POST_WRITE`            | 32       | persist changes in the persistence system using the [data persisters](data-persisters.md) (`POST`, `PUT`, `DELETE`)
 `SerializeListener`           | `kernel.view`      | `PRE_SERIALIZE`, `POST_SERIALIZE`    | 16       | serialize the PHP entity in string [according to the request format](content-negotiation.md)
 `RespondListener`             | `kernel.view`      | `PRE_RESPOND`, `POST_RESPOND`        | 8        | transform serialized to a `Symfony\Component\HttpFoundation\Response` instance
 `AddLinkHeaderListener`       | `kernel.response`  | None                                 | 0        | add a `Link` HTTP header pointing to the Hydra documentation

core/operations.md

@@ -67,7 +67,7 @@ use ApiPlatform\Core\Annotation\ApiResource;
  * @ApiResource(
  *     collectionOperations={"get"},
  *     itemOperations={"get"}
- *     )
+ * )
  */
 class Book
 {
@@ -88,7 +88,7 @@ use ApiPlatform\Core\Annotation\ApiResource;
  * @ApiResource(
  *     collectionOperations={"get"={"method"="GET"}},
  *     itemOperations={"get"={"method"="GET"}}
- *     )
+ * )
  */
 class Book
 {

core/serialization.md

@@ -405,7 +405,7 @@ The Normalizer class is a bit harder to understand because it has to make sure t
 
 namespace App\Serializer;
 
-class BookAttributeNormalizer implements NormalizerInterface, SerializerAwareInterface
+class BookAttributeNormalizer implements ContextAwareNormalizerInterface, SerializerAwareInterface
 {
     use SerializerAwareTrait;
 

core/validation.md

@@ -167,6 +167,70 @@ Of course, you can use XML or YAML configuration format instead of annotations i
 You may also pass in a [group sequence](http://symfony.com/doc/current/validation/sequence_provider.html) in place of
 the array of group names.
 
+## Using Validation Groups on Operations
+
+You can have different validation for each [operation](operations.md) related to your resource.
+
+```php
+<?php
+// api/src/Entity/Book.php
+
+use ApiPlatform\Core\Annotation\ApiResource;
+use Symfony\Component\Validator\Constraints as Assert;
+
+/**
+ * @ApiResource(
+ *     collectionOperations={
+ *         "get",
+ *         "post"={"validation_groups"={"Default", "postValidation"}}
+ *     },
+ *     itemOperations={
+ *         "delete",
+ *         "get",
+ *         "put"={"validation_groups"={"Default", "putValidation"}}
+ *     }
+ * )
+ * ...
+ */
+class Book
+{
+    /**
+     * @Assert\Uuid
+     */
+    private $id;
+
+    /**
+     * @Assert\NotBlank(groups={"postValidation"})
+     */
+    private $name;
+
+    /**
+     * @Assert\NotNull
+     * @Assert\Length(
+     *     min = 2,
+     *     max = 50,
+     *     groups={"postValidation"}
+     * )
+     * @Assert\Length(
+     *     min = 2,
+     *     max = 70,
+     *     groups={"putValidation"}
+     * )
+     */
+    private $author;
+
+    // ...
+}
+```
+
+With this configuration, there are three validation groups:
+
+`Default` contains the constraints that belong to no other group.
+
+`postValidation` contains the constraints on the name and author (length from 2 to 50) fields only.
+
+`putValidation` contains the constraints on the author (length from 2 to 70) field only.
+
 ## Dynamic Validation Groups
 
 If you need to dynamically determine which validation groups to use for an entity in different scenarios, just pass in a

deployment/kubernetes.md

@@ -30,6 +30,12 @@ package manager) chart to deploy in a wink on any of these platforms.
 
 ## Deploying
 
+Firstly you need to update helm dependencies by running:
+
+    helm dependency update ./api/helm/api
+
+You are now ready to deploy the API!
+
 Deploy your API to the container:
 
     helm install ./api/helm/api --namespace=baz --name baz \