Merge pull request #1391 from alanpoulain/merge-2.6

Author: alanpoulain

client-generator/nextjs.md

@@ -28,8 +28,10 @@ Install required dependencies:
 
     $ npx @api-platform/client-generator https://demo.api-platform.com . --generator next --resource book
     # Replace the URL by the entrypoint of your Hydra-enabled API
+    # Omit the resource flag to generate files for all resource types exposed by the API.
 
-> Note: Omit the resource flag to generate files for all resource types exposed by the API.
+> Note: On the [API Platform distribution](https://github.com/api-platform/api-platform), you can run
+> `generate-api-platform-client` instead of `npx @api-platform/client-generator`.
 
 ## Starting the Project
 

client-generator/react.md

@@ -61,7 +61,7 @@ Omit the resource flag to generate files for all resource types exposed by the A
 If you don't use the standalone installation, run the following command instead:
 
 ```console
-npx @api-platform/client-generator https://demo.api-platform.com src/ --resource book
+npx @api-platform/client-generator https://demo.api-platform.com src/ --resource book -g react
 ```
 
 Replace the URL with the entrypoint of your Hydra-enabled API.

client-generator/troubleshooting.md

@@ -55,3 +55,7 @@ cause: null } }
 Check access to the specified URL, in this case `https://demo.api-platform.com/contexts/Entrypoint`, use curl to check
 access and the response `curl https://demo.api-platform.com/contexts/Entrypoint`. In the above case an "Access Denied"
 message in JSON format was being returned.  
+
+## Docker distribution on Windows and hot-reloading
+
+Due to [a long-time known Docker for Windows issue](https://forums.docker.com/t/file-system-watch-does-not-work-with-mounted-volumes/12038), the files changes on the host are not notified on the `pwa` container. It causes the hot-reloading feature to not working properly for Windows users.

client-generator/vuetify.md

@@ -2,7 +2,7 @@
 
 ## Install with Docker
 
-If you use the API Platform distribution with docker, first you have to add the [Vue CLI](https://cli.vuejs.org/guide/) to the `yarn global add` command in `client/Dockerfile`:
+If you use the API Platform distribution with docker, first you have to add the [Vue CLI](https://cli.vuejs.org/guide/) to the `yarn global add` command in `pwa/Dockerfile`:
 
 ```dockerfile
 RUN yarn global add @api-platform/client-generator @vue/cli @vue/cli-service-global

core/configuration.md

@@ -425,8 +425,7 @@ api_platform:
         stateless: ~
 
         # The URL generation strategy to use for IRIs
-        # Use values from UrlGeneratorInterface
-        url_generation_strategy: ~
+        url_generation_strategy: !php/const ApiPlatform\Core\Api\UrlGeneratorInterface::ABS_PATH
 
         # ...
 ```

core/content-negotiation.md

@@ -2,7 +2,7 @@
 
 The API system has built-in [content negotiation](https://en.wikipedia.org/wiki/Content_negotiation) capabilities.
 
-By default, only the [JSON-LD](https://json-ld.org) format is enabled. However API Platform Core supports many more formats and can be extended.
+By default, only the [JSON-LD](https://json-ld.org) and JSON formats are enabled. However API Platform Core supports many more formats and can be extended.
 
 The framework natively supports JSON-LD (and Hydra), GraphQL, JSON:API, HAL, YAML, CSV, HTML (API docs), raw JSON and raw XML.
 Using the raw JSON or raw XML formats is discouraged, prefer using JSON-LD instead, which provides more feature and is as easy to use.
@@ -52,6 +52,7 @@ api_platform:
         yaml:     ['application/x-yaml']
         csv:      ['text/csv']
         html:     ['text/html']
+        myformat: ['application/vnd.myformat']
 ```
 
 To enable GraphQL support, [read the dedicated chapter](graphql.md).

core/controllers.md

@@ -35,8 +35,11 @@ First, let's create your custom operation:
 namespace App\Controller;
 
 use App\Entity\Book;
+use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
+use Symfony\Component\HttpKernel\Attribute\AsController;
 
-class CreateBookPublication
+#[AsController]
+class CreateBookPublication extends AbstractController
 {
     private $bookPublishingHandler;
 
@@ -98,10 +101,10 @@ use App\Controller\CreateBookPublication;
         'path' => '/books/{id}/publication',
         'controller' => CreateBookPublication::class,
     ],
-])
+])]
 class Book
 {
-    //...
+    // ...
 }
 ```
 
@@ -157,24 +160,20 @@ use ApiPlatform\Core\Annotation\ApiResource;
 use App\Controller\CreateBookPublication;
 use Symfony\Component\Serializer\Annotation\Groups;
 
-/**
- * @ApiResource(itemOperations={
- *     "get",
- *     "post_publication"={
- *         "method"="POST",
- *         "path"="/books/{id}/publication",
- *         "controller"=CreateBookPublication::class,
- *         "normalization_context"={"groups"={"publication"}},
- *     }
- * })
- */
+#[ApiResource(itemOperations: [
+    'get',
+    'post_publication' => [
+        'method' => 'POST',
+        'path' => '/books/{id}/publication',
+        'controller' => CreateBookPublication::class,
+        'normalization_context' => ['groups' => 'publication'],
+    ],
+])]
 class Book
 {
-    //...
+    // ...
 
-    /**
-     * @Groups("publication")
-     */
+    #[Groups(['publication'])]
     public $isbn;
 
     // ...
@@ -236,20 +235,18 @@ operation attribute:
 use ApiPlatform\Core\Annotation\ApiResource;
 use App\Controller\CreateBookPublication;
 
-/**
- * @ApiResource(itemOperations={
- *     "get",
- *     "post_publication"={
- *         "method"="POST",
- *         "path"="/books/{id}/publication",
- *         "controller"=CreateBookPublication::class,
- *         "read"=false,
- *     }
- * })
- */
+#[ApiResource(itemOperations: [
+    'get',
+    'post_publication' => [
+        'method' => 'POST',
+        'path' => '/books/{id}/publication',
+        'controller' => CreateBookPublication::class,
+        'read' => false,
+    ],
+])]
 class Book
 {
-    //...
+    // ...
 }
 ```
 
@@ -312,16 +309,14 @@ First, let's create your resource configuration:
 
 use ApiPlatform\Core\Annotation\ApiResource;
 
-/**
- * @ApiResource(itemOperations={
- *     "get",
- *     "post_publication"={"route_name"="book_post_publication"},
-*      "book_post_discontinuation",
- * })
- */
+#[ApiResource(itemOperations: [
+    'get',
+    'post_publication' => ['route_name' => 'book_post_publication'],
+    'book_post_discontinuation',
+])]
 class Book
 {
-    //...
+    // ...
 }
 ```
 
@@ -367,9 +362,12 @@ and its related route using annotations:
 namespace App\Controller;
 
 use App\Entity\Book;
+use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
+use Symfony\Component\HttpKernel\Attribute\AsController;
 use Symfony\Component\Routing\Annotation\Route;
 
-class CreateBookPublication
+#[AsController]
+class CreateBookPublication extends AbstractController
 {
     private $bookPublishingHandler;
 
@@ -378,17 +376,15 @@ class CreateBookPublication
         $this->bookPublishingHandler = $bookPublishingHandler;
     }
 
-    /**
-     * @Route(
-     *     name="book_post_publication",
-     *     path="/books/{id}/publication",
-     *     methods={"POST"},
-     *     defaults={
-     *         "_api_resource_class"=Book::class,
-     *         "_api_item_operation_name"="post_publication"
-     *     }
-     * )
-     */
+    #[Route(
+        name: 'book_post_publication',
+        path: '/books/{id}/publication',
+        methods: ['POST'],
+        defaults: [
+            '_api_resource_class' => Book::class,
+            '_api_item_operation_name' => 'post_publication',
+        ],
+    )]
     public function __invoke(Book $book): Book
     {
         $this->bookPublishingHandler->handle($book);
@@ -412,7 +408,9 @@ namespace App\Controller;
 
 use App\Entity\Book;
 use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
+use Symfony\Component\HttpKernel\Attribute\AsController;
 
+#[AsController]
 class BookController extends AbstractController
 {
     public function createPublication(Book $book, BookPublishingHandler $bookPublishingHandler): Book

core/data-persisters.md

@@ -155,7 +155,7 @@ services:
 
 ## Calling multiple DataPersisters
 
-Our DataPersisters are called in chain, once a data persister is supported the chain breaks and API Platform assumes your data is persisted. You can call mutliple data persisters by implementing the `ResumableDataPersisterInterface`:
+Our DataPersisters are called in chain, once a data persister is supported the chain breaks and API Platform assumes your data is persisted. You can call multiple data persisters by implementing the `ResumableDataPersisterInterface`:
 
 ```php
 namespace App\DataPersister;
@@ -189,4 +189,53 @@ 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.
+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:
+```php
+namespace App\DataPersister;
+
+use ApiPlatform\Core\DataPersister\ContextAwareDataPersisterInterface;
+use Doctrine\ORM\EntityManagerInterface;
+use App\Entity\BlogPost;
+
+final class BlogPostDataPersister implements ContextAwareDataPersisterInterface, ResumableDataPersisterInterface 
+{
+    private $entityManager;
+    
+    public function __construct(EntityManagerInterface $entityManager)
+    {
+        $this->entityManager = $entityManager;
+    }
+    
+    public function supports($data, array $context = []): bool
+    {
+        return $data instanceof BlogPost;
+    }
+
+    public function persist($data, array $context = [])
+    {
+        $this->entityManager->persist($data);
+        $this->entityManager->flush();
+    }
+
+    public function remove($data, array $context = [])
+    {
+        $this->entityManager->remove($data);
+        $this->entityManager->flush();
+    }
+
+    // Once called this data persister will resume to the next one
+    public function resumable(array $context = []): bool 
+    {
+        return true;
+    }
+}
+```
+```yaml
+# api/config/services.yaml
+services:
+    # ...
+    App\DataPersister\BlogPostDataPersister: ~
+        # Uncomment only if autoconfiguration is disabled
+        #arguments: ['@App\DataPersister\BlogPostDataPersister.inner']
+        #tags: [ 'api_platform.data_persister' ]
+```

core/default-order.md

@@ -5,6 +5,8 @@ API Platform Core provides an easy way to override the default order of items in
 By default, items in the collection are ordered in ascending (ASC) order by their resource identifier(s). If you want to
 customize this order, you must add an `order` attribute on your ApiResource annotation:
 
+[codeSelector]
+
 ```php
 <?php
 // api/src/Entity/Book.php
@@ -28,9 +30,21 @@ class Book
 }
 ```
 
+```yaml
+# api/config/api_platform/resources/Book.yaml
+App\Entity\Book:
+    attributes:
+        order:
+            foo: ASC
+```
+
+[/codeSelector]
+
 This `order` attribute is used as an array: the key defines the order field, the values defines the direction.
 If you only specify the key, `ASC` direction will be used as default. For example, to order by `foo` & `bar`:
 
+[codeSelector]
+
 ```php
 <?php
 // api/src/Entity/Book.php
@@ -59,8 +73,19 @@ class Book
 }
 ```
 
+```yaml
+# api/config/api_platform/resources/Book.yaml
+App\Entity\Book:
+    attributes:
+        order: ['foo', 'bar']
+```
+
+[/codeSelector]
+
 It's also possible to configure the default order on an association property:
 
+[codeSelector]
+
 ```php
 <?php
 // api/src/Entity/Book.php
@@ -84,8 +109,19 @@ class Book
 }
 ```
 
+```yaml
+# api/config/api_platform/resources/Book.yaml
+App\Entity\Book:
+    attributes:
+        order: ['author.username']
+```
+
+[/codeSelector]
+
 Another possibility is to apply the default order for a specific collection operation, which will override the global default order configuration.
 
+[codeSelector]
+
 ```php
 /**
  *     collectionOperations={
@@ -106,3 +142,21 @@ class Book
     // ...
 }
 ```
+
+```yaml
+# api/config/api_platform/resources/Book.yaml
+App\Entity\Book:
+    get: ~
+    get_desc_custom:
+        method: get
+        path: custom_collection_desc_foos
+        order:
+            name: DESC
+    get_asc_custom:
+        method: get
+        path: custom_collection_asc_foos
+        order:
+            name: ASC
+```
+
+[/codeSelector]