Merge pull request #1476 from alanpoulain/merge-2.6

Author: alanpoulain

.proselintrc renamed to .proselintrc.json

@@ -3,6 +3,7 @@
     "typography.symbols": false,
     "typography.exclamation": false,
     "hyperbole.misc": false,
-    "cliches.misc": false
+    "cliches.misc": false,
+    "lexical_illusions.misc": false
   }
 }

admin/file-upload.md

@@ -33,4 +33,6 @@ export default () => (
 ```
 
 And that's it!
-You don't need to decorate the data provider if you are using the Hydra one: it detects that you have used a `FileInput` and uses a `multipart/form-data` request instead of a JSON-LD one.
+The guessers are able to detect that you have used a `FileInput` and are passing this information to the data provider, through a `hasFileField` field in the `extraInformation` object, itself in the data.
+If you are using the Hydra data provider, it uses a `multipart/form-data` request instead of a JSON-LD one.
+In the case of the `EditGuesser`, the HTTP method used also becomes a `POST` instead of a `PUT`, to prevent a [PHP bug](https://bugs.php.net/bug.php?id=55815).

admin/performance.md

@@ -27,7 +27,7 @@ use Doctrine\ORM\Mapping as ORM;
 /**
  * @ORM\Entity
  */
- #[ApiResource]
+#[ApiResource]
 class Author
 {
     /**

admin/validation.md

@@ -20,9 +20,7 @@ use Symfony\Component\Validator\Constraints as Assert;
 #[ApiResource]
 class Book
 {
-    /**
-     * @Assert\NotBlank
-     */
+    #[Assert\NotBlank]
     public ?string $title = null;
 }
 ```
@@ -54,9 +52,7 @@ use Symfony\Component\Validator\Constraints as Assert;
 #[ApiResource]
 class Book
 {
-    /**
-     * @Assert\Isbn
-     */
+    #[Assert\Isbn]
     public ?string $isbn = null;
 }
 ```

core/configuration.md

@@ -15,10 +15,6 @@ api_platform:
     # The version of the API.
     version: '0.0.0'
 
-    # Return IRIs as Absolute URLs.
-    # ex: http://example.com/authors/1
-    absolute_url: false
-
     # Set this to false if you want Webby to disappear.
     show_webby: true
 

core/content-negotiation.md

@@ -97,7 +97,7 @@ api_platform:
 Support for specific formats can also be configured at resource and operation level using the `input_formats` and `output_formats` attributes.
 `input_formats` controls the formats accepted in request bodies while `output_formats` controls formats available for responses.
 
-The `format` attribute can be used as a shortcut, it sets both the `input_formats` and `output_formats` in one time.
+The `formats` attribute can be used as a shortcut, it sets both the `input_formats` and `output_formats` in one time.
 
 ```php
 <?php

core/controllers.md

@@ -378,12 +378,9 @@ use Symfony\Component\Routing\Annotation\Route;
 #[AsController]
 class CreateBookPublication extends AbstractController
 {
-    private $bookPublishingHandler;
-
-    public function __construct(BookPublishingHandler $bookPublishingHandler)
-    {
-        $this->bookPublishingHandler = $bookPublishingHandler;
-    }
+    public function __construct(
+        private BookPublishingHandler $bookPublishingHandler
+    ) {}
 
     #[Route(
         name: 'book_post_publication',

core/data-persisters.md

@@ -52,13 +52,13 @@ final class BlogPostDataPersister implements ContextAwareDataPersisterInterface
 
     public function persist($data, array $context = [])
     {
-      // call your persistence layer to save $data
-      return $data;
+        // call your persistence layer to save $data
+        return $data;
     }
 
     public function remove($data, array $context = [])
     {
-      // call your persistence layer to delete $data
+        // call your persistence layer to delete $data
     }
 }
 ```
@@ -173,13 +173,13 @@ final class BlogPostDataPersister implements ContextAwareDataPersisterInterface,
 
     public function persist($data, array $context = [])
     {
-      // call your persistence layer to save $data
-      return $data;
+        // call your persistence layer to save $data
+        return $data;
     }
 
     public function remove($data, array $context = [])
     {
-      // call your persistence layer to delete $data
+        // call your persistence layer to delete $data
     }
 
     // Once called this data persister will resume to the next one
@@ -190,7 +190,7 @@ final class BlogPostDataPersister implements ContextAwareDataPersisterInterface,
 }
 ```
 
-This is very useful when using [`Messenger` with API Platform](messenger.md) as you may want to do something asynchronously with the data but still call the default Doctrine data persister, for example:
+This is useful when using [`Messenger` with API Platform](messenger.md) as you may want to do something asynchronously with the data but still call the default Doctrine data persister, for example:
 
 ```php
 namespace App\DataPersister;

core/data-providers.md

@@ -13,17 +13,17 @@ retrieve data for a given resource will be used.
 
 For a given resource, you can implement two kinds of interface:
 
-* the [`CollectionDataProviderInterface`](https://github.com/api-platform/core/blob/main/src/DataProvider/CollectionDataProviderInterface.php)
+* the [`CollectionDataProviderInterface`](https://github.com/api-platform/core/blob/main/src/Core/DataProvider/CollectionDataProviderInterface.php)
   is used when fetching a collection.
-* the [`ItemDataProviderInterface`](https://github.com/api-platform/core/blob/main/src/DataProvider/ItemDataProviderInterface.php)
+* the [`ItemDataProviderInterface`](https://github.com/api-platform/core/blob/main/src/Core/DataProvider/ItemDataProviderInterface.php)
   is used when fetching items.
 
 Both implementations can also implement a third, optional, interface called
-['RestrictedDataProviderInterface'](https://github.com/api-platform/core/blob/main/src/DataProvider/RestrictedDataProviderInterface.php)
+['RestrictedDataProviderInterface'](https://github.com/api-platform/core/blob/main/src/Core/DataProvider/RestrictedDataProviderInterface.php)
 if you want to limit their effects to a single resource or operation.
 
 In the following examples we will create custom data providers for an entity class called `App\Entity\BlogPost`.
-Note, that if your entity is not Doctrine-related, you need to flag the identifier property by using `#[ApiProperty(identifier: true)]` for things to work properly (see also [Entity Identifier Case](serialization.md#entity-identifier-case)).
+Note, that if your entity is not Doctrine-related, you need to flag the identifier property by using `#[ApiProperty(identifier: true)` for things to work properly (see also [Entity Identifier Case](serialization.md#entity-identifier-case)).
 
 ## Custom Collection Data Provider
 
@@ -33,9 +33,9 @@ If the [Symfony MakerBundle](https://symfony.com/doc/current/bundles/SymfonyMake
 bin/console make:data-provider --collection-only
 ```
 
-First, your `BlogPostCollectionDataProvider` has to implement the [`CollectionDataProviderInterface`](https://github.com/api-platform/core/blob/main/src/DataProvider/CollectionDataProviderInterface.php):
+First, your `BlogPostCollectionDataProvider` has to implement the [`CollectionDataProviderInterface`](https://github.com/api-platform/core/blob/main/src/Core/DataProvider/CollectionDataProviderInterface.php):
 
-The `getCollection` method must return an `array`, a `Traversable` or a [`ApiPlatform\Core\DataProvider\PaginatorInterface`](https://github.com/api-platform/core/blob/main/src/DataProvider/PaginatorInterface.php) instance.
+The `getCollection` method must return an `array`, a `Traversable` or a [`ApiPlatform\Core\DataProvider\PaginatorInterface`](https://github.com/api-platform/core/blob/main/src/Core/DataProvider/PaginatorInterface.php) instance.
 If no data is available, you should return an empty array.
 
 ```php
@@ -91,7 +91,7 @@ If the [Symfony MakerBundle](https://symfony.com/doc/current/bundles/SymfonyMake
 bin/console make:data-provider --item-only
 ```
 
-The process is similar for item data providers. Create a `BlogPostItemDataProvider` implementing the [`ItemDataProviderInterface`](https://github.com/api-platform/core/blob/main/src/DataProvider/ItemDataProviderInterface.php)
+The process is similar for item data providers. Create a `BlogPostItemDataProvider` implementing the [`ItemDataProviderInterface`](https://github.com/api-platform/core/blob/main/src/Core/DataProvider/ItemDataProviderInterface.php)
 interface:
 
 The `getItem` method can return `null` if no result has been found.

core/default-order.md

@@ -50,7 +50,7 @@ namespace App\Entity;
 
 use ApiPlatform\Metadata\ApiResource;
 
-#[ApiResource(order: ['foo' => 'bar'])]
+#[ApiResource(order: ['foo', 'bar'])]
 class Book
 {
     // ...
@@ -126,8 +126,8 @@ use ApiPlatform\Metadata\ApiResource;
 
 #[ApiResource]
 #[GetCollection]
-#[GetCollection(name: 'desc_custom', uriTemplate: 'custom_collection_desc_foos', order: ['name' => 'DESC'])]
-#[GetCollection(name: 'asc_custom', uriTemplate: 'custom_collection_asc_foos', order: ['name' => 'ASC'])]
+#[GetCollection(name: 'get_desc_custom', uriTemplate: 'custom_collection_desc_foos', order: ['name' => 'DESC'])]
+#[GetCollection(name: 'get_asc_custom', uriTemplate: 'custom_collection_asc_foos', order: ['name' => 'ASC'])]
 class Book
 {
     // ...

core/deprecations.md

@@ -121,7 +121,10 @@ namespace App\Entity;
 
 use ApiPlatform\Metadata\ApiResource;
 
-#[ApiResource(deprecationReason:"Create a Book instead", sunset: "01/01/2020")]
+#[ApiResource(
+    deprecationReason: 'Create a Book instead',
+    sunset: '01/01/2020'
+)]
 class Parchment
 {
     // ...
@@ -142,7 +145,10 @@ use ApiPlatform\Metadata\ApiResource;
 use ApiPlatform\Metadata\Get;
 
 #[ApiResource]
-#[Get(sunset: '01/01/2020', deprecationReason: 'Retrieve a Book instead')]
+#[Get(
+    deprecationReason: 'Retrieve a Book instead',
+    sunset: '01/01/2020'
+)]
 class Parchment
 {
     // ...

core/dto.md

@@ -1,6 +1,6 @@
 # Using Data Transfer Objects (DTOs)
 
- As stated in [the general design considerations](design.md), in most cases [the DTO pattern](https://en.wikipedia.org/wiki/Data_transfer_object) should be implemented using an API Resource class representing the public data model exposed through the API and [a custom data provider](data-providers.md). In such cases, the class marked with `#[ApiResource]` will act as a DTO.
+As stated in [the general design considerations](design.md), in most cases [the DTO pattern](https://en.wikipedia.org/wiki/Data_transfer_object) should be implemented using an API Resource class representing the public data model exposed through the API and [a custom data provider](data-providers.md). In such cases, the class marked with `#[ApiResource]` will act as a DTO.
 
 However, it's sometimes useful to use a specific class to represent the input or output data structure related to an operation.
 
@@ -75,7 +75,8 @@ We have the following `BookInput`:
 
 namespace App\Dto;
 
-final class BookInput {
+final class BookInput
+{
     /**
      * @var string
      */
@@ -104,6 +105,7 @@ final class BookInputDataTransformer implements DataTransformerInterface
     {
         $book = new Book();
         $book->isbn = $data->isbn;
+
         return $book;
     }
 
@@ -142,7 +144,8 @@ To manage the output, it's exactly the same process. For example, we have the fo
 
 namespace App\Dto;
 
-final class BookOutput {
+final class BookOutput
+{
     /**
      * @var string
      */
@@ -171,6 +174,7 @@ final class BookOutputDataTransformer implements DataTransformerInterface
     {
         $output = new BookOutput();
         $output->name = $data->name;
+
         return $output;
     }
 
@@ -213,7 +217,8 @@ With the following `BookInput`:
 
 namespace App\Dto;
 
-final class BookInput {
+final class BookInput
+{
   /**
    * @var \App\Entity\Author
    */
@@ -242,6 +247,7 @@ final class BookInputDataTransformer implements DataTransformerInterface
     {
         $existingBook = $context[AbstractItemNormalizer::OBJECT_TO_POPULATE];
         $existingBook->author = $data->author;
+
         return $existingBook;
     }
 
@@ -268,6 +274,79 @@ services:
         #tags: [ 'api_platform.data_transformer' ]
 ```
 
+## Initialize the Input DTO For Partial Update
+
+In order to be able to do a partial update (`PATCH`), it is needed to initialize the input DTO with the existing data before the deserialization process.
+
+This way, the input DTO will be correctly validated with its old data and partial new data.
+
+Create a class implementing the `DataTransformerInitializerInterface` instead of the `DataTransformerInterface`:
+
+```php
+<?php
+// src/DataTransformer/BookInputDataTransformerInitializer.php
+
+namespace App\DataTransformer;
+
+use ApiPlatform\Core\DataTransformer\DataTransformerInitializerInterface;
+use ApiPlatform\Core\Serializer\AbstractItemNormalizer;
+use App\Entity\Book;
+use App\Dto\BookInput;
+
+final class BookInputDataTransformerInitializer implements DataTransformerInitializerInterface
+{
+    /**
+     * {@inheritdoc}
+     */
+    public function transform($data, string $to, array $context = [])
+    {
+        $existingBook = $context[AbstractItemNormalizer::OBJECT_TO_POPULATE];
+        $existingBook->author = $data->author;
+
+        return $existingBook;
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function initialize(string $inputClass, array $context = [])
+    {
+        $existingBook = $context[AbstractItemNormalizer::OBJECT_TO_POPULATE] ?? null;
+        if (!$existingBook) {
+            return new BookInput();
+        }
+
+        $bookInput = new BookInput();
+        $bookInput->author = $existingBook->author;
+
+        return $bookInput;
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function supportsTransformation($data, string $to, array $context = []): bool
+    {
+        if ($data instanceof Book) {
+          return false;
+        }
+
+        return Book::class === $to && null !== ($context['input']['class'] ?? null);
+    }
+}
+```
+
+Register it:
+
+```yaml
+# api/config/services.yaml
+services:
+    # ...
+    'App\DataTransformer\BookInputDataTransformerInitializer': ~
+        # Uncomment only if autoconfiguration is disabled
+        #tags: [ 'api_platform.data_transformer' ]
+```
+
 ## Disabling the Input or the Output
 
 Both the `input` and the `output` attributes can be set to `false`. If `input` is `false`, the deserialization process
@@ -285,6 +364,8 @@ will be skipped. If `output` is `false`, the serialization process will be skipp
 namespace App\Entity;
 
 use ApiPlatform\Metadata\ApiResource;
+use ApiPlatform\Metadata\Post;
+use ApiPlatform\Metadata\Put;
 use App\Dto\BookOutput;
 use App\Dto\CreateBook;
 use App\Dto\UpdateBook;

core/events.md

@@ -27,7 +27,7 @@ Name                          | Event              | [Pre & Post hooks](#custom-
 `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`, `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`)
+`DeserializeListener`         | `kernel.request`   | `PRE_DESERIALIZE`, `POST_DESERIALIZE`       | 2        | Deserializes data into a PHP entity (`POST`); 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`)
@@ -61,7 +61,7 @@ Attribute      | Type   | Default | Description
 
 Registering your own event listeners to add extra logic is convenient.
 
-The [`ApiPlatform\Core\EventListener\EventPriorities`](https://github.com/api-platform/core/blob/main/src/EventListener/EventPriorities.php) class comes with a convenient set of class constants corresponding to commonly used priorities:
+The [`ApiPlatform\Core\EventListener\EventPriorities`](https://github.com/api-platform/core/blob/main/src/Core/EventListener/EventPriorities.php) class comes with a convenient set of class constants corresponding to commonly used priorities:
 
 Constant           | Event             | Priority |
 -------------------|-------------------|----------|