fix #504

Author: soyuka

core/serialization.md

@@ -139,7 +139,7 @@ App\Entity\Book:
 ```
 
 In the previous example, the `name` property will be visible when reading (`GET`) the object, and it will also be available
-to write (`PUT/POST`). The `author` property will be write-only; it will not be visible when serialized responses are 
+to write (`PUT/POST`). The `author` property will be write-only; it will not be visible when serialized responses are
 returned by the API.
 
 Internally, API Platform passes the value of the `normalization_context` as the 3rd argument of [the `Serializer::serialize()` method](https://api.symfony.com/master/Symfony/Component/Serializer/SerializerInterface.html#method_serialize) during the normalization
@@ -222,9 +222,9 @@ In the following JSON document, the relation from a book to an author is represe
 }
 ```
 
-However, for performance reasons, it is sometimes preferable to avoid forcing the client to issue extra HTTP requests. 
-It is possible to embed related objects (in their entirety, or only some of their properties) directly in the parent 
-response through the use of serialization groups. By using the following serialization groups annotations (`@Groups`), 
+However, for performance reasons, it is sometimes preferable to avoid forcing the client to issue extra HTTP requests.
+It is possible to embed related objects (in their entirety, or only some of their properties) directly in the parent
+response through the use of serialization groups. By using the following serialization groups annotations (`@Groups`),
 a JSON representation of the author is embedded in the book response:
 
 ```php
@@ -419,7 +419,7 @@ final class BookContextBuilder implements SerializerContextBuilderInterface
     {
         $context = $this->decorated->createFromRequest($request, $normalization, $extractedAttributes);
         $resourceClass = $context['resource_class'] ?? null;
-        
+
         if ($resourceClass === Book::class && isset($context['groups']) && $this->authorizationChecker->isGranted('ROLE_ADMIN') && false === $normalization) {
             $context['groups'][] = 'admin:input';
         }
@@ -429,17 +429,17 @@ final class BookContextBuilder implements SerializerContextBuilderInterface
 }
 ```
 
-If the user has the `ROLE_ADMIN` permission and the subject is an instance of Book, `admin_input` group will be dynamically added to the 
-denormalization context. The `$normalization` variable lets you check whether the context is for normalization (if `TRUE`) or denormalization 
+If the user has the `ROLE_ADMIN` permission and the subject is an instance of Book, `admin_input` group will be dynamically added to the
+denormalization context. The `$normalization` variable lets you check whether the context is for normalization (if `TRUE`) or denormalization
 (`FALSE`).
 
 ## Changing the Serialization Context on a Per-item Basis
 
-The example above demonstrates how you can modify the normalization/denormalization context based on the current user 
+The example above demonstrates how you can modify the normalization/denormalization context based on the current user
 permissions for all books. Sometimes, however, the permissions vary depending on what book is being processed.
 
-Think of ACL's: User "A" may retrieve Book "A" but not Book "B". In this case, we need to leverage the power of the 
-Symfony Serializer and register our own normalizer that adds the group on every single item (note: priority `64` is 
+Think of ACL's: User "A" may retrieve Book "A" but not Book "B". In this case, we need to leverage the power of the
+Symfony Serializer and register our own normalizer that adds the group on every single item (note: priority `64` is
 an example; it is always important to make sure your normalizer gets loaded first, so set the priority to whatever value
 is appropriate for your application; higher values are loaded earlier):
 
@@ -452,7 +452,7 @@ services:
             - { name: 'serializer.normalizer', priority: 64 }
 ```
 
-The Normalizer class is a bit harder to understand, because it must ensure that it is only called once and that there is no recursion. 
+The Normalizer class is a bit harder to understand, because it must ensure that it is only called once and that there is no recursion.
 To accomplish this, it needs to be aware of the parent Normalizer instance itself.
 
 Here is an example:
@@ -492,7 +492,7 @@ class BookAttributeNormalizer implements ContextAwareNormalizerInterface, Normal
 
         return $this->normalizer->normalize($object, $format, $context);
     }
-    
+
     public function supportsNormalization($data, $format = null, array $context = [])
     {
         // Make sure we're not called twice
@@ -502,7 +502,7 @@ class BookAttributeNormalizer implements ContextAwareNormalizerInterface, Normal
 
         return $data instanceof Book;
     }
-    
+
     private function userHasPermissionsForBook($object): bool
     {
         // Get permissions from user in $this->tokenStorage
@@ -512,10 +512,10 @@ class BookAttributeNormalizer implements ContextAwareNormalizerInterface, Normal
 }
 ```
 
-This will add the serialization group `can_retrieve_book` only if the currently logged-in user has access to the given book 
+This will add the serialization group `can_retrieve_book` only if the currently logged-in user has access to the given book
 instance.
 
-Note: In this example, we use the `TokenStorageInterface` to verify access to the book instance. However, Symfony 
+Note: In this example, we use the `TokenStorageInterface` to verify access to the book instance. However, Symfony
 provides many useful other services that might be better suited to your use case. For example, the [`AuthorizationChecker`](https://symfony.com/doc/current/components/security/authorization.html#authorization-checker).
 
 ## Name Conversion
@@ -539,7 +539,7 @@ api_platform:
 
 ## Decorating a Serializer and Adding Extra Data
 
-In the following example, we will see how we add extra informations to the serialized output. Here is how we add the 
+In the following example, we will see how we add extra informations to the serialized output. Here is how we add the
 date on each request in `GET`:
 
 ```yaml
@@ -598,7 +598,7 @@ final class ApiNormalizer implements NormalizerInterface, DenormalizerInterface,
     {
         return $this->decorated->denormalize($data, $class, $format, $context);
     }
-    
+
     public function setSerializer(SerializerInterface $serializer)
     {
         if($this->decorated instanceof SerializerAwareInterface) {
@@ -624,7 +624,7 @@ the `ApiPlatform\Core\Annotation\ApiProperty` annotation. For example:
 class Book
 {
     // ...
-    
+
     /**
      * @ApiProperty(identifier=true)
      */
@@ -659,7 +659,7 @@ App\Entity\Book:
 ```
 
 In some cases, you will want to set the identifier of a resource from the client (e.g. a client-side generated UUID, or a slug).
-In such cases, you must make the identifier property a writable class property. Specifically, to use client-generated IDs, you 
+In such cases, you must make the identifier property a writable class property. Specifically, to use client-generated IDs, you
 must do the following:
 
 1. create a setter for the identifier of the entity (e.g. `public function setId(string $id)`) or make it a `public` property ,
@@ -718,3 +718,69 @@ The JSON output will now include the embedded context:
   "author": "/people/59"
 }
 ```
+
+## Collection relation
+
+This is a special case where, in an entity, you have a `toMany` relation. By default, Doctrine will use an `ArrayCollection` to store your values. This is fine when you have a *read* operation, but when you try to *write* you can observe some an issue where the response is not reflecting the changes correctly. It can lead to client errors even though the update was correct.
+Indeed, after an update on this relation, the collection looks wrong because `ArrayCollection`'s indexes are not sequential. To change this, we recommend to use a getter that returns `$collectionRelation->getValues()`. Thanks to this, the relation is now a real array which is sequentially indexed.
+
+```php
+<?php
+
+namespace App\Entity;
+
+use ApiPlatform\Core\Annotation\ApiResource;
+use Doctrine\Common\Collections\ArrayCollection;
+use Doctrine\ORM\Mapping as ORM;
+
+/**
+ * @ApiResource
+ * @ORM\Entity
+ */
+final class Brand
+{
+    /**
+     * @ORM\Id
+     * @ORM\Column(type="integer")
+     * @ORM\GeneratedValue(strategy="AUTO")
+     */
+    private $id;
+
+    /**
+     * @ORM\ManyToMany(targetEntity="App\Entity\Car", inversedBy="brands")
+     * @ORM\JoinTable(
+     *     name="CarToBrand",
+     *     joinColumns={@ORM\JoinColumn(name="brand_id", referencedColumnName="id", nullable=false)},
+     *     inverseJoinColumns={@ORM\JoinColumn(name="car_id", referencedColumnName="id", nullable=false)}
+     * )
+     */
+    private $cars;
+
+    public function __construct()
+    {
+        $this->cars = new ArrayCollection();
+    }
+
+    public function addCar(DummyCar $car)
+    {
+        $this->cars[] = $car;
+    }
+
+    public function removeCar(DummyCar $car)
+    {
+        $this->cars->removeElement($car);
+    }
+
+    public function getCars()
+    {
+        return $this->cars->getValues();
+    }
+
+    public function getId()
+    {
+        return $this->id;
+    }
+}
+```
+
+For reference please check [#1534](https://github.com/api-platform/core/pull/1534).

core/validation.md

@@ -367,3 +367,36 @@ api_platform:
 ```
 
 In this example, only `severity` and `anotherPayloadField` will be serialized.
+
+## Validation on collection relations
+
+Note: this is related to the [collection relation denormalization](./serialization.md#collection-relation).
+You may have an issue when trying to validate a relation representing a collection (`toMany`). After fixing the denormalization by using a getter that returns `$collectionRelation->getValues()`, you should define your validation on the getter instead of the property.
+
+For example:
+
+```xml
+<getter property="cars">
+    <constraint name="Valid"/>
+</getter>
+```
+
+```php
+final class Brand
+{
+    // ...
+
+    public function __construct()
+    {
+        $this->cars = new ArrayCollection();
+    }
+
+    /**
+     * @Assert\Valid
+     */
+    public function getCars()
+    {
+        return $this->cars->getValues();
+    }
+}
+```