docs: 2.7 update

review @soyuka
review @dunglas

Author: Thibaudeau Pierre

admin/handling-relations.md

@@ -150,10 +150,9 @@ This API uses the following PHP code:
 ```php
 <?php
 // api/src/Entity/Review.php
-
 namespace App\Entity;
 
-use ApiPlatform\Core\Annotation\ApiResource;
+use ApiPlatform\Metadata\ApiResource;
 use Doctrine\ORM\Mapping as ORM;
 
 /**
@@ -179,11 +178,10 @@ class Review
 ```php
 <?php
 // api/src/Entity/Book.php
-
 namespace App\Entity;
 
 use ApiPlatform\Core\Annotation\ApiFilter;
-use ApiPlatform\Core\Annotation\ApiResource;
+use ApiPlatform\Metadata\ApiResource;
 use ApiPlatform\Core\Bridge\Doctrine\Orm\Filter\SearchFilter;
 use Doctrine\Common\Collections\ArrayCollection;
 use Doctrine\ORM\Mapping as ORM;

admin/performance.md

@@ -17,12 +17,11 @@ you can make sure the authors are retrieved in one go by writing:
 ```php
 <?php
 // api/src/Entity/Author.php
-
 namespace App\Entity;
 
 use ApiPlatform\Core\Annotation\ApiFilter;
-use ApiPlatform\Core\Annotation\ApiResource;
 use ApiPlatform\Core\Bridge\Doctrine\Orm\Filter\SearchFilter;
+use ApiPlatform\Metadata\ApiResource;
 use Doctrine\ORM\Mapping as ORM;
 
 /**
@@ -35,8 +34,8 @@ class Author
      * @ORM\Column(type="integer")
      * @ORM\GeneratedValue
      * @ORM\Id
-     * @ApiFilter(SearchFilter::class, strategy="exact")
      */
+    #[ApiFilter(SearchFilter::class, strategy: "exact")]
     public $id;
 
     /**

admin/schema.org.md

@@ -16,11 +16,12 @@ To configure which property should be shown to represent your entity, map the pr
 
 ```php
 // api/src/Entity/Person.php
+...
 
-/**
- * @ApiProperty(iri="http://schema.org/name")
- */
+#[ApiProperty(types: ["http://schema.org/name"])]
 private $name;
+
+...
 ```
 
 ## Emails, URLs and Identifiers

admin/validation.md

@@ -12,13 +12,12 @@ For instance, with API Platform Core as backend, if you write the following:
 ```php
 <?php
 // api/src/Entity/Book.php
+namespace App\Entity;
 
-use ApiPlatform\Core\Annotation\ApiResource;
+use ApiPlatform\Metadata\ApiResource;
 use Symfony\Component\Validator\Constraints as Assert;
 
-/**
- * @ApiResource
- */
+#[ApiResource]
 class Book
 {
     /**
@@ -47,13 +46,12 @@ For example if you have this code:
 ```php
 <?php
 // api/src/Entity/Book.php
+namespace App\Entity;
 
-use ApiPlatform\Core\Annotation\ApiResource;
+use ApiPlatform\Metadata\ApiResource;
 use Symfony\Component\Validator\Constraints as Assert;
 
-/**
- * @ApiResource
- */
+#[ApiResource]
 class Book
 {
     /**

core/content-negotiation.md

@@ -102,12 +102,11 @@ The `format` attribute can be used as a shortcut, it sets both the `input_format
 ```php
 <?php
 // api/src/Entity/Book.php
-
 namespace App\Entity;
 
-use ApiPlatform\Core\Annotation\ApiResource;
+use ApiPlatform\Metadata\ApiResource;
 
- #[ApiResource(formats: ['xml', 'jsonld', 'csv' => ['text/csv']])]
+#[ApiResource(formats: ['xml', 'jsonld', 'csv' => ['text/csv']])]
 class Book
 {
     // ...
@@ -127,21 +126,17 @@ You can specify different accepted formats at operation level too, it's especial
 ```php
 <?php
 // api/src/Entity/Book.php
-
 namespace App\Entity;
 
-use ApiPlatform\Core\Annotation\ApiResource;
-
-#[ApiResource(
-    formats: ['jsonld', 'csv' => ['text/csv']],
-    itemOperations: [
-        'patch' => [
-            'input_formats' => [
-                'json' => ['application/merge-patch+json'],
-            ],
-        ],
-    ],
-)]
+use ApiPlatform\Metadata\ApiResource;
+use ApiPlatform\Metadata\Patch;
+use ApiPlatform\Metadata\GetCollection;
+use ApiPlatform\Metadata\Post;
+
+#[ApiResource(formats: ['jsonld', 'csv' => ['text/csv']])]
+#[Patch(inputFormats: ['json' => ['application/merge-patch+json']])]
+#[GetCollection]
+#[Post]
 class Book
 {
     // ...
@@ -227,7 +222,6 @@ services:
 ```php
 <?php
 // api/src/Serializer/CustomItemNormalizer.php
-
 namespace App\Serializer;
 
 use Symfony\Component\Serializer\Normalizer\DenormalizerInterface;
@@ -274,7 +268,6 @@ flatten or remove overly complex relations:
 ```php
 <?php
 // api/src/Serializer/CustomItemNormalizer.php
-
 namespace App\Serializer;
 
 use Symfony\Component\Serializer\Normalizer\DenormalizerInterface;

core/controllers.md

@@ -31,7 +31,6 @@ First, let's create your custom operation:
 ```php
 <?php
 // api/src/Controller/CreateBookPublication.php
-
 namespace App\Controller;
 
 use App\Entity\Book;
@@ -90,18 +89,20 @@ The routing has not been configured yet because we will add it at the resource c
 ```php
 <?php
 // api/src/Entity/Book.php
+namespace App\Entity;
 
-use ApiPlatform\Core\Annotation\ApiResource;
+use ApiPlatform\Metadata\ApiResource;
+use ApiPlatform\Metadata\Get;
+use ApiPlatform\Metadata\Post;
 use App\Controller\CreateBookPublication;
 
-#[ApiResource(itemOperations: [
-    'get',
-    'post_publication' => [
-        'method' => 'POST',
-        'path' => '/books/{id}/publication',
-        'controller' => CreateBookPublication::class,
-    ],
-])]
+#[ApiResource]
+#[Get]
+#[Post(
+    name: 'publication', 
+    uriTemplate: '/books/{id}/publication', 
+    controller: CreateBookPublication::class
+)]
 class Book
 {
     // ...
@@ -155,20 +156,22 @@ You may want different serialization groups for your custom operations. Just con
 ```php
 <?php
 // api/src/Entity/Book.php
+namespace App\Entity;
 
-use ApiPlatform\Core\Annotation\ApiResource;
+use ApiPlatform\Metadata\ApiResource;
+use ApiPlatform\Metadata\Get;
+use ApiPlatform\Metadata\Post;
 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]
+#[Get]
+#[Post(
+    name: 'publication', 
+    uriTemplate: '/books/{id}/publication', 
+    controller: CreateBookPublication::class, 
+    normalizationContext: ['groups' => 'publication']
+)]
 class Book
 {
     // ...
@@ -231,19 +234,21 @@ operation attribute:
 ```php
 <?php
 // api/src/Entity/Book.php
+namespace App\Entity;
 
-use ApiPlatform\Core\Annotation\ApiResource;
+use ApiPlatform\Metadata\ApiResource;
+use ApiPlatform\Metadata\Get;
+use ApiPlatform\Metadata\Post;
 use App\Controller\CreateBookPublication;
 
-#[ApiResource(itemOperations: [
-    'get',
-    'post_publication' => [
-        'method' => 'POST',
-        'path' => '/books/{id}/publication',
-        'controller' => CreateBookPublication::class,
-        'read' => false,
-    ],
-])]
+#[ApiResource]
+#[Get]
+#[Post(
+    name: 'publication', 
+    uriTemplate: '/books/{id}/publication', 
+    controller: CreateBookPublication::class, 
+    read: false
+)]
 class Book
 {
     // ...
@@ -309,14 +314,16 @@ First, let's create your resource configuration:
 ```php
 <?php
 // api/src/Entity/Book.php
+namespace App\Entity;
 
-use ApiPlatform\Core\Annotation\ApiResource;
+use ApiPlatform\Metadata\ApiResource;
+use ApiPlatform\Metadata\Get;
+use ApiPlatform\Metadata\Post;
 
-#[ApiResource(itemOperations: [
-    'get',
-    'post_publication' => ['route_name' => 'book_post_publication'],
-    'book_post_discontinuation',
-])]
+#[ApiResource]
+#[Get]
+#[Post(name: 'publication', routeName: 'book_post_publication')]
+#[Post(name: 'book_post_discontinuation')]
 class Book
 {
     // ...
@@ -361,7 +368,6 @@ and its related route using annotations:
 ```php
 <?php
 // api/src/Controller/CreateBookPublication.php
-
 namespace App\Controller;
 
 use App\Entity\Book;
@@ -406,7 +412,6 @@ the same thing as the previous example:
 ```php
 <?php
 // api/src/Controller/BookController.php
-
 namespace App\Controller;
 
 use App\Entity\Book;

core/data-providers.md

@@ -23,7 +23,7 @@ Both implementations can also implement a third, optional, interface called
 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
 
@@ -266,8 +266,6 @@ using it within your data provider.
 <?php
 // api/src/DataProvider/CustomCollectionDataProvider.php
 
-declare(strict_types=1);
-
 namespace App\DataProvider;
 
 use ApiPlatform\Core\DataProvider\CollectionDataProviderInterface;

core/default-order.md

@@ -12,11 +12,9 @@ customize this order, you must add an `order` attribute on your ApiResource anno
 // api/src/Entity/Book.php
 namespace App\Entity;
 
-use ApiPlatform\Core\Annotation\ApiResource;
+use ApiPlatform\Metadata\ApiResource;
 
-/**
- * @ApiResource(attributes={"order"={"foo": "ASC"}})
- */
+#[ApiResource(order: ['foo' => 'ASC'])]
 class Book
 {
     // ...
@@ -50,11 +48,9 @@ If you only specify the key, `ASC` direction will be used as default. For exampl
 // api/src/Entity/Book.php
 namespace App\Entity;
 
-use ApiPlatform\Core\Annotation\ApiResource;
+use ApiPlatform\Metadata\ApiResource;
 
-/**
- * @ApiResource(attributes={"order"={"foo", "bar"}})
- */
+#[ApiResource(order: ['foo' => 'bar'])]
 class Book
 {
     // ...
@@ -91,11 +87,9 @@ It's also possible to configure the default order on an association property:
 // api/src/Entity/Book.php
 namespace App\Entity;
 
-use ApiPlatform\Core\Annotation\ApiResource;
+use ApiPlatform\Metadata\ApiResource;
 
-/**
- * @ApiResource(attributes={"order"={"author.username"}})
- */
+#[ApiResource(order: ['author.username'])]
 class Book
 {
     // ...
@@ -123,13 +117,17 @@ Another possibility is to apply the default order for a specific collection oper
 [codeSelector]
 
 ```php
-/**
- *     collectionOperations={
- *         "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"}},
- *     }
- */
+<?php
+// api/src/Entity/Book.php
+namespace App\Entity;
+
+use ApiPlatform\Metadata\GetCollection;
+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'])]
 class Book
 {
     // ...