Merge 2.6

client-generator/react-native.md

@@ -7,7 +7,7 @@
 To use this generator you need [Node.js](https://nodejs.org/) and [Yarn](https://yarnpkg.com/) (or [npm](https://www.npmjs.com/)) installed.
 To run the command line tool, we also recommend using [npx](https://www.npmjs.com/package/npx).
 
-Create a React Native application using [Expo CLI](https://docs.expo.io/versions/latest/workflow/expo-cli).
+Create a React Native application using [Expo CLI](https://docs.expo.io/workflow/expo-cli/).
 
 ```console
 yarn global add expo-cli

client-generator/vuetify.md

@@ -150,7 +150,7 @@ The generator comes with a i18n feature to allow quick translations of some labe
 work, you need to create this file:
 
 ```javascript
-// src/plugins/vuetify.js
+// src/i18n.js
 import Vue from 'vue';
 import VueI18n from 'vue-i18n';
 import messages from './locales/en';
@@ -210,10 +210,10 @@ Update your App.vue:
       <v-toolbar-title>Application</v-toolbar-title>
     </v-app-bar>
 
-    <v-content>
+    <v-main>
       <Breadcrumb layout-class="pl-3 py-3" />
       <router-view></router-view>
-    </v-content>
+    </v-main>
     <v-footer color="indigo" app>
       <span class="white--text">&copy; 2019</span>
     </v-footer>

core/controllers.md

@@ -66,7 +66,7 @@ This action will be automatically registered as a service (the service name is t
 `App\Controller\CreateBookPublication`).
 
 API Platform automatically retrieves the appropriate PHP entity using the data provider then deserializes user data in it,
-and for `POST` and `PUT` requests updates the entity with data provided by the user.
+and for `POST`, `PUT` and `PATCH` requests updates the entity with data provided by the user.
 
 The entity is retrieved in the `__invoke` method thanks to a dedicated argument resolver.
 
@@ -289,6 +289,9 @@ App\Entity\Book:
 This way, it will skip the `ReadListener`. You can do the same for some other built-in listeners. See [Built-in Event Listeners](events.md#built-in-event-listeners)
 for more information.
 
+In your custom controller, the `__invoke()` method parameter should be called the same as the entity identifier.
+So for the path `/user/{uuid}/bookmarks`, you must use `__invoke(string $uuid)`.
+
 ## Alternative Method
 
 There is another way to create a custom operation. However, we do not encourage its use. Indeed, this one disperses

core/dto.md

@@ -203,7 +203,9 @@ services:
 
 ## Updating a Resource with a Custom Input
 
-When performing an update (e.g. `PUT` operation), the resource to be updated is read by ApiPlatform before the deserialization phase. To do so, it uses a [data provider](data-providers.md) with the `:id` parameter given in the URL. The *body* of the request is the JSON object sent by the client, it is deserialized and is used to update the previously found resource.
+When performing an update (e.g. `PUT` operation), the resource to be updated is read by API Platform before the deserialization phase.
+To do so, it uses a [data provider](data-providers.md) with the `:id` parameter given in the URL.
+The *body* of the request is the JSON object sent by the client, it is deserialized and is used to update the previously found resource.
 
 ![Diagram put input output](images/diagrams/api-platform-put-i-o.svg)
 

core/events.md

@@ -22,20 +22,20 @@ are also available if you want to hook into the persistence layer's object lifec
 
 These built-in event listeners are registered for routes managed by API Platform:
 
-Name                             | Event              | [Pre & Post hooks](#custom-event-listeners) | Priority | Description
----------------------------------|--------------------|---------------------------------------------|----------|-------------
-`AddFormatListener`              | `kernel.request`   | None                                        | 28       | Guesses the best response format ([content negotiation](content-negotiation.md))
+Name                          | Event              | [Pre & Post hooks](#custom-event-listeners) | Priority | Description
+------------------------------|--------------------|---------------------------------------------|----------|-------------
+`AddFormatListener`           | `kernel.request`   | None                                        | 7        | Guesses the best response format ([content negotiation](content-negotiation.md))
 `QueryParameterValidateListener` | `kernel.request`   | None                                        | 16       | Validates query parameters
-`ReadListener`                   | `kernel.request`   | `PRE_READ`, `POST_READ`                     | 4        | Retrieves data from the persistence system using the [data providers](data-providers.md) (`GET`, `PUT`, `DELETE`)
-`DeserializeListener`            | `kernel.request`   | `PRE_DESERIALIZE`, `POST_DESERIALIZE`       | 2        | Deserializes data into a PHP entity (`GET`, `POST`, `DELETE`); updates the entity retrieved using the data provider (`PUT`)
-`DenyAccessListener`             | `kernel.request`   | None                                        | 1        | Enforces [access control](security.md) using Security expressions
-`ValidateListener`               | `kernel.view`      | `PRE_VALIDATE`, `POST_VALIDATE`             | 64       | [Validates data](validation.md) (`POST`, `PUT`)
-`WriteListener`                  | `kernel.view`      | `PRE_WRITE`, `POST_WRITE`                   | 32       | Persists changes in the persistence system using the [data persisters](data-persisters.md) (`POST`, `PUT`, `DELETE`)
-`SerializeListener`              | `kernel.view`      | `PRE_SERIALIZE`, `POST_SERIALIZE`           | 16       | Serializes the PHP entity in string [according to the request format](content-negotiation.md)
-`RespondListener`                | `kernel.view`      | `PRE_RESPOND`, `POST_RESPOND`               | 8        | Transforms serialized to a `Symfony\Component\HttpFoundation\Response` instance
-`AddLinkHeaderListener`          | `kernel.response`  | None                                        | 0        | Adds a `Link` HTTP header pointing to the Hydra documentation
-`ValidationExceptionListener`    | `kernel.exception` | None                                        | 0        | Serializes validation exceptions in the Hydra format
-`ExceptionListener`              | `kernel.exception` | None                                        | -96      | Serializes PHP exceptions in the Hydra format (including the stack trace in debug mode)
+`ReadListener`                | `kernel.request`   | `PRE_READ`, `POST_READ`                     | 4        | Retrieves data from the persistence system using the [data providers](data-providers.md) (`GET`, `PUT`, `PATCH`, `DELETE`)
+`DeserializeListener`         | `kernel.request`   | `PRE_DESERIALIZE`, `POST_DESERIALIZE`       | 2        | Deserializes data into a PHP entity (`GET`, `POST`, `DELETE`); updates the entity retrieved using the data provider (`PUT`, `PATCH`)
+`DenyAccessListener`          | `kernel.request`   | None                                        | 1        | Enforces [access control](security.md) using Security expressions
+`ValidateListener`            | `kernel.view`      | `PRE_VALIDATE`, `POST_VALIDATE`             | 64       | [Validates data](validation.md) (`POST`, `PUT`, `PATCH`)
+`WriteListener`               | `kernel.view`      | `PRE_WRITE`, `POST_WRITE`                   | 32       | Persists changes in the persistence system using the [data persisters](data-persisters.md) (`POST`, `PUT`, `PATCH`, `DELETE`)
+`SerializeListener`           | `kernel.view`      | `PRE_SERIALIZE`, `POST_SERIALIZE`           | 16       | Serializes the PHP entity in string [according to the request format](content-negotiation.md)
+`RespondListener`             | `kernel.view`      | `PRE_RESPOND`, `POST_RESPOND`               | 8        | Transforms serialized to a `Symfony\Component\HttpFoundation\Response` instance
+`AddLinkHeaderListener`       | `kernel.response`  | None                                        | 0        | Adds a `Link` HTTP header pointing to the Hydra documentation
+`ValidationExceptionListener` | `kernel.exception` | None                                        | 0        | Serializes validation exceptions in the Hydra format
+`ExceptionListener`           | `kernel.exception` | None                                        | -96      | Serializes PHP exceptions in the Hydra format (including the stack trace in debug mode)
 
 Some of these built-in listeners can be enabled/disabled by setting operation attributes:
 

core/filters.md

@@ -1627,7 +1627,7 @@ class DummyCar
     /**
      * @ORM\Column(type="string")
      */
-    #[ApiFilter(SearchFilter::class, strategy => 'partial')]
+    #[ApiFilter(SearchFilter::class, strategy: 'partial')]
     public $name;
 
     /**
@@ -1643,7 +1643,7 @@ class DummyCar
 On the first property, `name`, it's straightforward. The first annotation argument is the filter class, the second specifies options, here, the strategy:
 
 ```php
-#[ApiFilter(SearchFilter::class, strategy => 'partial')]
+#[ApiFilter(SearchFilter::class, strategy: 'partial')]
 ```
 
 In the second annotation, we specify `properties` on which the filter should apply. It's necessary here because we don't want to filter `colors` but the `prop` property of the `colors` association.
@@ -1674,7 +1674,7 @@ use Doctrine\ORM\Mapping as ORM;
 
 #[ApiResource]
 #[ApiFilter(BooleanFilter::class)]
-#[ApiFilter(DateFilter::class, strategy => DateFilter::EXCLUDE_NULL)]
+#[ApiFilter(DateFilter::class, strategy: DateFilter::EXCLUDE_NULL)]
 #[ApiFilter(SearchFilter::class, properties: ['colors.prop' => 'ipartial', 'name' => 'partial'])]
 #[ApiFilter(PropertyFilter::class, arguments: ['parameterName' => 'foobar'])]
 #[ApiFilter(GroupFilter::class, arguments: ['parameterName' => 'foobargroups'])]
@@ -1694,7 +1694,7 @@ The `BooleanFilter` is applied to every `Boolean` property of the class. Indeed,
 The `DateFilter` given here will be applied to every `Date` property of the `DummyCar` class with the `DateFilter::EXCLUDE_NULL` strategy:
 
 ```php
-#[ApiFilter(DateFilter::class, strategy => DateFilter::EXCLUDE_NULL)]
+#[ApiFilter(DateFilter::class, strategy: DateFilter::EXCLUDE_NULL)]
 ```
 
 The `SearchFilter` here adds properties. The result is the exact same as the example with annotations on properties:

core/operations.md

@@ -44,6 +44,8 @@ Note: the `PATCH` method must be enabled explicitly in the configuration, refer
 
 Note: with JSON Merge Patch, the [null values will be skipped](https://symfony.com/doc/current/components/serializer.html#skipping-null-values) in the response.
 
+Note: Current `PUT` implementation behaves more or less like the `PATCH` method. Existing properties not included in the payload are **not** removed, their current values are preserved. To remove an existing property, its value must be explicitly set to `null`. Implementing [the standard `PUT` behavior](https://httpwg.org/specs/rfc7231.html#PUT) is on the roadmap, follow [issue #4344] (https://github.com/api-platform/core/issues/4344) to track the progress.
+
 ## Enabling and Disabling Operations
 
 If no operation is specified, all default CRUD operations are automatically registered. It is also possible - and recommended
@@ -213,7 +215,7 @@ App\Entity\Book:
         get: ~
     itemOperations:
         get:
-            controller: App\Controller\NotFoundAction
+            controller: ApiPlatform\Core\Action\NotFoundAction
             read: false
             output: false
 ```
@@ -232,7 +234,7 @@ App\Entity\Book:
         </collectionOperations>
         <itemOperations>
             <itemOperation name="get">
-                <attribute name="controller">App\Controller\NotFoundAction</attribute>
+                <attribute name="controller">ApiPlatform\Core\Action\NotFoundAction</attribute>
                 <attribute name="read">false</attribute>
                 <attribute name="output">false</attribute>
             </itemOperation>
@@ -598,7 +600,7 @@ class Weather
     // ...
 ```
 
-This will expose the `Weather` model, but also all the default CRUD routes: `GET`, `PUT`, `DELETE` and `POST`, which is a non-sense in our context.
+This will expose the `Weather` model, but also all the default CRUD routes: `GET`, `PUT`, `PATCH`, `DELETE` and `POST`, which is a non-sense in our context.
 Since we are required to expose at least one route, let's expose just one:
 
 ```php

core/security.md

@@ -102,7 +102,8 @@ class Book
 App\Entity\Book:
     properties:
         adminOnlyProperty:
-            security: 'is_granted("ROLE_ADMIN")'
+            attributes:
+                security: 'is_granted("ROLE_ADMIN")'
 ```
 
 [/codeSelector]
@@ -123,7 +124,7 @@ Available variables are:
 * `request`: the current request
 
 Access control checks in the `security` attribute are always executed before the [denormalization step](serialization.md).
-It means than for `PUT` requests, `object` doesn't contain the value submitted by the user, but values currently stored in [the persistence layer](data-persisters.md).
+It means than for `PUT` or `PATCH` requests, `object` doesn't contain the value submitted by the user, but values currently stored in [the persistence layer](data-persisters.md).
 
 ## Executing Access Control Rules After Denormalization
 

core/serialization.md

@@ -139,7 +139,7 @@ Alternatively, you can use the more verbose syntax:
 ```
 
 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` / `PATCH` / `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
@@ -252,7 +252,8 @@ In the following JSON document, the relation from a book to an author is by defa
 
 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:
+a JSON representation of the author is embedded in the book response. As soon as any of the author's attributes is in
+the `book` group, the author will be embedded.
 
 [codeSelector]
 
@@ -282,6 +283,26 @@ class Book
 }
 ```
 
+```yaml
+# api/config/api_platform/resources/Book.yaml
+App\Entity\Book:
+    attributes:
+        normalization_context:
+            groups: ['book']
+
+# api/config/serializer/Book.yaml
+App\Entity\Book:
+    attributes:
+        name:
+            groups: ['book']
+        author:
+            groups: ['book']
+```
+
+[/codeSelector]
+
+[codeSelector]
+
 ```php
 <?php
 // api/src/Entity/Person.php
@@ -305,20 +326,6 @@ class Person
 ```
 
 ```yaml
-# api/config/api_platform/resources/Book.yaml
-App\Entity\Book:
-    attributes:
-        normalization_context:
-            groups: ['book']
-
-# api/config/serializer/Book.yaml
-App\Entity\Book:
-    attributes:
-        name:
-            groups: ['book']
-        author:
-            groups: ['book']
-
 # api/config/serializer/Person.yaml
 App\Entity\Person:
     attributes:
@@ -352,7 +359,7 @@ Instead of embedding relations in the main HTTP response, you may want [to "push
 
 ### Denormalization
 
-It is also possible to embed a relation in `PUT` and `POST` requests. To enable that feature, set the serialization groups
+It is also possible to embed a relation in `PUT`, `PATCH` and `POST` requests. To enable that feature, set the serialization groups
 the same way as normalization. For example:
 
 [codeSelector]