Merge pull request #1704 from alanpoulain/chore/merge-3.0

Author: alanpoulain

.github/workflows/ci.yml

@@ -1,8 +1,8 @@
 name: Lint
 
 on:
-  - push
-  - pull_request
+  push:
+  pull_request:
 
 jobs:
   build:
@@ -16,7 +16,7 @@ jobs:
           fetch-depth: 0
 
       - name: Lint
-        uses: github/super-linter@v3.17.0
+        uses: github/super-linter/slim@v4
         env:
           VALIDATE_ALL_CODEBASE: false
           VALIDATE_EDITORCONFIG: false

core/content-negotiation.md

@@ -23,7 +23,7 @@ Format                                                          | Format name  |
 [JSON-LD](https://json-ld.org)                                  | `jsonld`     | `application/ld+json`         | yes
 [GraphQL](graphql.md)                                           | n/a          | n/a                           | yes
 [JSON:API](http://jsonapi.org/)                                 | `jsonapi`    | `application/vnd.api+json`    | yes
-[HAL](http://stateless.co/hal_specification.html)               | `jsonhal`    | `application/hal+json`        | yes
+[HAL](https://stateless.group/hal_specification.html)           | `jsonhal`    | `application/hal+json`        | yes
 [YAML](http://yaml.org/)                                        | `yaml`       | `application/x-yaml`          | no
 [CSV](https://tools.ietf.org/html/rfc4180)                      | `csv`        | `text/csv`                    | no
 [HTML](https://whatwg.org/) (API docs)                          | `html`       | `text/html`                   | no

core/controllers.md

@@ -23,6 +23,10 @@ In the following examples, the built-in `GET` operation is registered as well as
 
 By default, API Platform uses the first `Get` operation defined to generate the IRI of an item and the first `GetCollection` operation to generate the IRI of a collection.
 
+If your resource does not have any `Get` operation, API Platform automatically adds an operation to help generating this IRI.
+If your resource has any identifier, this operation will look like `/books/{id}`. But if your resource doesn't have any identifier, API Platform will use the Skolem format `/.well-known/genid/{id}`.
+Those routes are not exposed from any documentation (for instance OpenAPI), but are anyway declared on the Symfony routing and always return a HTTP 404.
+
 If you create a custom operation, you will probably want to properly document it.
 See the [OpenAPI](openapi.md) part of the documentation to do so.
 
@@ -56,7 +60,7 @@ class CreateBookPublication extends AbstractController
 }
 ```
 
-This custom operation behaves exactly like the built-in operation: it returns a JSON-LD document corresponding to the id
+This custom operation behaves exactly like the built-in operation: it returns a JSON-LD document corresponding to the ID
 passed in the URL.
 
 Here we consider that [autowiring](https://symfony.com/doc/current/service_container/autowiring.html) is enabled for
@@ -144,9 +148,77 @@ App\Entity\Book:
 
 [/codeSelector]
 
-It is mandatory to set the `method`, `path` and `controller` attributes. They allow API Platform to configure the routing path and
+It is mandatory to set the `method`, `uriTemplate` and `controller` attributes. They allow API Platform to configure the routing path and
 the associated controller respectively.
 
+## Using the PlaceholderAction
+
+Complex use cases may lead you to create multiple custom operations.
+
+In such a case, you will probably create the same amount of custom controllers while you may not need to perform custom logic inside.
+
+To avoid that, API Platform provides the `ApiPlatform\Action\PlaceholderAction` which behaves the same when using the [built-in operations](operations.md#operations).
+
+You just need to set the `controller` attribute with this class. Here, the previous example updated:
+
+[codeSelector]
+
+```php
+// api/src/Entity/Book.php
+namespace App\Entity;
+
+use ApiPlatform\Action\PlaceholderAction;
+use ApiPlatform\Metadata\ApiResource;
+use ApiPlatform\Metadata\Get;
+use ApiPlatform\Metadata\Post;
+
+#[ApiResource(operations: [
+    new Get(),
+    new Post(
+        name: 'publication', 
+        uriTemplate: '/books/{id}/publication', 
+        controller: PlaceholderAction::class
+    )
+])]
+class Book
+{
+    // ...
+}
+```
+
+```yaml
+# api/config/api_platform/resources.yaml
+App\Entity\Book:
+    operations:
+        ApiPlatform\Metadata\Get: ~
+        post_publication:
+            class: ApiPlatform\Metadata\Post
+            method: POST
+            uriTemplate: /books/{id}/publication
+            controller: ApiPlatform\Action\PlaceholderAction
+```
+
+```xml
+<?xml version="1.0" encoding="UTF-8" ?>
+<!-- api/config/api_platform/resources.xml -->
+
+<resources
+        xmlns="https://api-platform.com/schema/metadata/resources-3.0"
+        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+        xsi:schemaLocation="https://api-platform.com/schema/metadata/resources-3.0
+        https://api-platform.com/schema/metadata/resources-3.0.xsd">
+    <resource class="App\Entity\Book">
+        <operations>
+            <operation class="ApiPlatform\Metadata\Get" />
+            <operation class="ApiPlatform\Metadata\Post" name="post_publication" uriTemplate="/books/{id}/publication"
+                       controller="ApiPlatform\Action\PlaceholderAction" />
+        </operations>
+    </resource>
+</resources>
+```
+
+[/codeSelector]
+
 ## Using Serialization Groups
 
 You may want different serialization groups for your custom operations. Just configure the proper `normalizationContext` and/or `denormalizationContext` in your operation:

core/dto.md

@@ -43,6 +43,7 @@ And the processor:
 namespace App\State;
 
 use App\Dto\UserResetPasswordDto;
+use ApiPlatform\Metadata\Operation;
 use ApiPlatform\State\ProcessorInterface;
 use Symfony\Component\HttpKernel\Exception\NotFoundHttpException;
 
@@ -107,6 +108,7 @@ namespace App\State;
 
 use App\Dto\AnotherRepresentation;
 use App\Model\Book;
+use ApiPlatform\Metadata\Operation;
 use ApiPlatform\State\ProviderInterface;
 
 final class BookRepresentationProvider implements ProviderInterface
@@ -117,3 +119,77 @@ final class BookRepresentationProvider implements ProviderInterface
     }
 }
 ```
+
+## Implementing a Write Operation With an Output Different From the Resource
+
+For returning another representation of your data in a [State Processor](./state-processors.md), you should specify your processor class in the `processor` attribute and same for your `output`.
+
+[codeSelector]
+
+```php
+<?php
+
+namespace App\Entity;
+
+use ApiPlatform\Metadata\Post;
+use App\Dto\AnotherRepresentation;
+use App\State\BookRepresentationProcessor;
+
+#[Post(output: AnotherRepresentation::class, processor: BookRepresentationProcessor::class)]
+class Book {}
+```
+```yaml
+# api/config/api_platform/resources.yaml
+App\Entity\Book:
+    operations:
+        ApiPlatform\Metadata\Post:
+            output: App\Dto\AnotherRepresentation
+            processor: App\State\BookRepresentationProcessor
+```
+```xml
+<?xml version="1.0" encoding="UTF-8" ?>
+<!-- api/config/api_platform/resources.xml -->
+
+<resources xmlns="https://api-platform.com/schema/metadata/resources-3.0"
+        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+        xsi:schemaLocation="https://api-platform.com/schema/metadata/resources-3.0
+        https://api-platform.com/schema/metadata/resources-3.0.xsd">
+    <resource class="App\Entity\Book">
+        <operations>
+            <operation class="ApiPlatform\Metadata\Post" 
+                       processor="App\State\BookRepresentationProcessor"
+                       output="App\Dto\AnotherRepresentation" /> 
+        </operations>
+    </resource>
+</resources>
+```
+
+[/codeSelector]
+
+Here the `$data` attribute represents an instance of your resource.
+
+```php
+<?php
+
+namespace App\State;
+
+use ApiPlatform\Metadata\Operation;
+use ApiPlatform\State\ProcessorInterface;
+use App\Dto\AnotherRepresentation;
+use App\Model\Book;
+
+final class BookRepresentationProcessor implements ProcessorInterface
+{
+     /**
+     * @param Book $data
+     */
+    public function process($data, Operation $operation, array $uriVariables = [], array $context = [])
+    {
+        return new AnotherRepresentation(
+            $data->getId(),
+            $data->getTitle(),
+            // etc.
+        );
+    }
+}
+```

core/elasticsearch.md

@@ -199,6 +199,8 @@ Keep in mind that it is your responsibility to populate your Elasticsearch index
 a custom [state processors](state-processors.md#creating-a-custom-state-processor) or any other mechanism that suits your
 project (such as an [ETL](https://en.wikipedia.org/wiki/Extract,_transform,_load)).
 
+To disable elasticsearch index discovery for non-elasticsearch entities you can set `elasticsearch: false` in the `#[ApiResource]` attribute. If this property is absent, all entities will perform an index check during cache warmup to determine if they are on elasticsearch or not.
+
 You're done! The API is now ready to use.
 
 ### Creating custom mapping

core/errors.md

@@ -125,9 +125,9 @@ use App\Exception\ProductWasRemovedException;
 use App\Exception\ProductNotFoundException;
 
 #[ApiResource(
-    exceptionToStatus: ['ProductNotFoundException::class' => 404]
+    exceptionToStatus: [ProductNotFoundException::class => 404]
     operations: [
-        new Get(exceptionToStatus: ['ProductWasRemovedException::class' => 410]),
+        new Get(exceptionToStatus: [ProductWasRemovedException::class => 410]),
         new GetCollection(),
         new Post()
     ]

core/extending.md

@@ -15,9 +15,9 @@ The following tables summarizes which extension point to use depending on what y
 | [State Processors](state-processors)                                                           | custom business logic and computations to trigger before or after persistence (ex: mail, call to an external API...)                                                                                                                |
 | [Normalizers](serialization.md#decorating-a-serializer-and-adding-extra-data)                  | customize the resource sent to the client (add fields in JSON documents, encode codes, dates...)                                                                                                                                    |
 | [Filters](filters.md)                                                                          | create filters for collections and automatically document them (OpenAPI, GraphQL, Hydra)                                                                                                                                            |
-| [Serializer Context Builders](serialization.md#changing-the-serialization-context-dynamically) | Changing the Serialization context (e.g. groups) dynamically                                                                                                                                                                        |
+| [Serializer Context Builders](serialization.md#changing-the-serialization-context-dynamically) | change the Serialization context (e.g. groups) dynamically                                                                                                                                                                        |
 | [Messenger Handlers](messenger.md)                                                             | create 100% custom, RPC, async, service-oriented endpoints (should be used in place of custom controllers because the messenger integration is compatible with both REST and GraphQL, while custom controllers only work with REST) |
-| [DTOs and Data Transformers](dto.md)                                                           | use a specific class to represent the input or output data structure related to an operation                                                                                                                                        |
+| [DTOs](dto.md)                                                           | use a specific class to represent the input or output data structure related to an operation                                                                                                                                        |
 | [Kernel Events](events.md)                                                                     | customize the HTTP request or response (REST only, other extension points must be preferred when possible)                                                                                                                          |
 
 ## Doctrine Specific Extension Points

core/extensions.md

@@ -60,6 +60,7 @@ namespace App\Doctrine;
 use ApiPlatform\Doctrine\Orm\Extension\QueryCollectionExtensionInterface;
 use ApiPlatform\Doctrine\Orm\Extension\QueryItemExtensionInterface;
 use ApiPlatform\Doctrine\Orm\Util\QueryNameGeneratorInterface;
+use ApiPlatform\Metadata\Operation;
 use App\Entity\Offer;
 use Doctrine\ORM\QueryBuilder;
 use Symfony\Component\Security\Core\Security;
@@ -73,12 +74,12 @@ final class CurrentUserExtension implements QueryCollectionExtensionInterface, Q
         $this->security = $security;
     }
 
-    public function applyToCollection(QueryBuilder $queryBuilder, QueryNameGeneratorInterface $queryNameGenerator, string $resourceClass, string $operationName = null): void
+    public function applyToCollection(QueryBuilder $queryBuilder, QueryNameGeneratorInterface $queryNameGenerator, string $resourceClass, Operation $operation = null, array $context = []): void
     {
         $this->addWhere($queryBuilder, $resourceClass);
     }
 
-    public function applyToItem(QueryBuilder $queryBuilder, QueryNameGeneratorInterface $queryNameGenerator, string $resourceClass, array $identifiers, string $operationName = null, array $context = []): void
+    public function applyToItem(QueryBuilder $queryBuilder, QueryNameGeneratorInterface $queryNameGenerator, string $resourceClass, array $identifiers, Operation $operation = null, array $context = []): void
     {
         $this->addWhere($queryBuilder, $resourceClass);
     }

core/filters.md

@@ -951,7 +951,7 @@ App\Entity\Tweet:
 
 [/codeSelector]
 
-Given that the collection endpoint is `/tweets`, you can filter tweets by id and date in ascending or descending order:
+Given that the collection endpoint is `/tweets`, you can filter tweets by ID and date in ascending or descending order:
 `/tweets?order[id]=asc&order[date]=desc`.
 
 By default, whenever the query does not specify the direction explicitly (e.g: `/tweets?order[id]&order[date]`), filters
@@ -1173,8 +1173,8 @@ to retrieve items, [extensions](extensions.md) are the way to go.
 A Doctrine ORM filter is basically a class implementing the `ApiPlatform\Doctrine\Orm\Filter\FilterInterface`.
 API Platform includes a convenient abstract class implementing this interface and providing utility methods: `ApiPlatform\Doctrine\Orm\Filter\AbstractFilter`.
 
-In the following example, we create a class to filter a collection by applying a regexp to a property. The `REGEXP` DQL
-function used in this example can be found in the [`DoctrineExtensions`](https://github.com/beberlei/DoctrineExtensions)
+In the following example, we create a class to filter a collection by applying a regular expression to a property.
+The `REGEXP` DQL function used in this example can be found in the [`DoctrineExtensions`](https://github.com/beberlei/DoctrineExtensions)
 library. This library must be properly installed and registered to use this example (works only with MySQL).
 
 ```php
@@ -1191,7 +1191,7 @@ use Symfony\Component\PropertyInfo\Type;
 
 final class RegexpFilter extends AbstractFilter
 {
-    protected function filterProperty(string $property, $value, QueryBuilder $queryBuilder, QueryNameGeneratorInterface $queryNameGenerator, string $resourceClass, Operation $operation = null, array $context = [])
+    protected function filterProperty(string $property, $value, QueryBuilder $queryBuilder, QueryNameGeneratorInterface $queryNameGenerator, string $resourceClass, Operation $operation = null, array $context = []): void
     {
         // otherwise filter is applied to order and page as well
         if (
@@ -1518,7 +1518,7 @@ final class UserFilter extends SQLFilter
             // Don't worry, getParameter automatically escapes parameters
             $userId = $this->getParameter('id');
         } catch (\InvalidArgumentException $e) {
-            // No user id has been defined
+            // No user ID has been defined
             return '';
         }
 

core/getting-started.md

@@ -183,7 +183,7 @@ resources:
 <?xml version="1.0" encoding="UTF-8" ?>
 <!-- api/config/api_platform/resources.xml -->
 
-<resource xmlns="https://api-platform.com/schema/metadata/resources-3.0"
+<resources xmlns="https://api-platform.com/schema/metadata/resources-3.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="https://api-platform.com/schema/metadata/resources-3.0
         https://api-platform.com/schema/metadata/resources-3.0.xsd">