Update graphql, events & extending docs for Laravel and v4 (#2026)

* Update event listener configuration for API Platform 4.0 Updated the documentation to reflect the requirement of `use_symfony_listeners: true` for activating event listeners in API Platform 4.0. Also reformatted existing notes for better clarity and added separation lines for improved readability. * Add documentation on system providers and processors This commit introduces detailed documentation on the workflow of state providers and processors in the system. It includes a schema, examples of decorating providers and processors, and specific implementations for both Symfony and Laravel frameworks. * Update GraphQL docs to include Laravel-specific instructions This update adds detailed instructions for enabling and configuring GraphQL in a Laravel environment, complementing the existing Symfony guidance. It covers installation, route configurations, disabling features, custom resolvers, and altering default settings specific to Laravel, ensuring comprehensive and platform-specific documentation. * Remove specific framework & Docker for GraphQL installation commands * Refactor GraphQL & extending documentations for clarity and accuracy Updated terminology from "stages" to "providers and processors" for better clarity. Removed redundant sections to streamline information on custom mutations and configuration examples. * Fix capitalize title Co-authored-by: Kévin Dunglas <[email protected]> * Fix capitalize title Co-authored-by: Kévin Dunglas <[email protected]> * Fix capitalize title Co-authored-by: Kévin Dunglas <[email protected]> * Fix capitalize title Co-authored-by: Kévin Dunglas <[email protected]> * Fix title Co-authored-by: Kévin Dunglas <[email protected]> * Fix title Co-authored-by: Kévin Dunglas <[email protected]> * Fix titles and coding style * Fix wrong implementation & rm duplicate code * Fix spelling and class rendering Co-authored-by: Antoine Bluchet <[email protected]> * Fix title with a better title name Co-authored-by: Antoine Bluchet <[email protected]> * Fix title with a better title name Co-authored-by: Antoine Bluchet <[email protected]> * Fix remove unused method Co-authored-by: Antoine Bluchet <[email protected]> * Fix remove unused method Co-authored-by: Antoine Bluchet <[email protected]> * Fix remove unused method Co-authored-by: Antoine Bluchet <[email protected]> * Fix by rephrasing not available commands message Co-authored-by: Antoine Bluchet <[email protected]> * Fix better explanations to enable GraphQL Co-authored-by: Antoine Bluchet <[email protected]> * Fix remove unused declaration in the Laravel container Co-authored-by: Antoine Bluchet <[email protected]> * Fix typo Co-authored-by: Alan Poulain <[email protected]> * Fix typo Co-authored-by: Alan Poulain <[email protected]> * Fix spelling Co-authored-by: Alan Poulain <[email protected]> * Fix typo Co-authored-by: Alan Poulain <[email protected]> * Fix typo Co-authored-by: Alan Poulain <[email protected]> * Fix missing var assignation Co-authored-by: Alan Poulain <[email protected]> * Add recommendation for using system providers and processors * Add GraphQL state provider access checker notes & cleanup * Completes GraphQL doc for Laravel support & clarified some points reviewed * Fix string syntax error Co-authored-by: Alan Poulain <[email protected]> * Apply suggestions from code review --------- Co-authored-by: Kévin Dunglas <[email protected]> Co-authored-by: Antoine Bluchet <[email protected]> Co-authored-by: Alan Poulain <[email protected]>
api-platform · Oct 4, 2024 · d84cd2f · d84cd2f
1 parent 4881e9e
commit d84cd2f
Show file tree

Hide file tree

Showing 3 changed files with 531 additions and 259 deletions.
diff --git a/core/events.md b/core/events.md
@@ -1,9 +1,13 @@
 # The Event System
 
-In API Platform 3.2 you may need `event_listeners_backward_compatibility_layer: true` to keep event listeners activated.
+> [!WARNING]
+> In API Platform 4.0 with Symfony, you need `use_symfony_listeners: true` to activate event listeners.
 
-Note: using Kernel event with API Platform should be mostly limited to tweaking the generated HTTP response. Also, GraphQL is **not supported**.
-[For most use cases, better extension points, working both with REST and GraphQL, are available](extending.md).
+---
+
+> [!NOTE]
+> Using Kernel event with API Platform should be mostly limited to tweaking the generated HTTP response. Also, GraphQL is **not supported**.
+> We recommend to use [System providers and processors](extending.md#system-providers-and-processors) to extend API Platform internals.
 
 API Platform Core implements the [Action-Domain-Responder](https://github.com/pmjones/adr) pattern. This implementation
 is covered in depth in the [Creating custom operations and controllers](operations.md#creating-custom-operations-and-controllers)

diff --git a/core/extending.md b/core/extending.md
@@ -36,3 +36,115 @@ For instance, if you want to send a mail after a resource has been persisted, bu
 To replace existing API Platform services with your decorators, [check out how to decorate services](https://symfony.com/doc/current/service_container/service_decoration.html).
 
 <p align="center" class="symfonycasts"><a href="https://symfonycasts.com/screencast/api-platform-security/service-decoration?cid=apip"><img src="../symfony/images/symfonycasts-player.png" alt="Service Decoration screencast"><br>Watch the Service Decoration screencast</a></p>
+
+## System Providers and Processors
+
+The system is based on a workflow composed of **state providers** and **state processors**.
+
+The schema below describes them:
+
+```mermaid
+---
+title: System providers and processors
+---
+flowchart TB
+    C1(ReadProvider) --> C2(AccessCheckerProvider)
+    C2 --> C3(DeserializeProvider)
+    C3 --> C4(ParameterProvider)
+    C4 --> C5(ValidateProcessor)
+    C5 --> C6(WriteProcessor)
+    C6 --> C7(SerializeProcessor)
+```
+
+### Symfony Access Checker Provider
+
+When using Symfony, the access checker provider is used at three different stages:
+- `api_platform.state_provider.access_checker.post_validate` decorates the `ValidateProvider`
+- `api_platform.state_provider.access_checker.post_deserialize` decorates the `DeserializeProvider`
+- `api_platform.state_provider.access_checker` decorates the `ReadProvider`
+
+> [!NOTE]
+> For graphql use: `api_platform.graphql.state_provider.access_checker.post_deserialize`,
+> `api_platform.graphql.state_provider.access_checker.post_validate`, `api_platform.graphql.state_provider.validate` and
+> `api_platform.graphql.state_provider.access_checker.after_resolver`
+
+### Decoration Example
+
+Here is an example of the decoration of the RespondProcessor:
+
+Starts by creating your `CustomRespondProcessor`:
+
+```php
+<?php
+namespace App\State;
+
+use ApiPlatform\State\ProcessorInterface;
+
+final class CustomRespondProcessor implements ProcessorInterface
+{
+    public function __construct(private readonly ProcessorInterface $processor) {}
+
+    public function process(mixed $data, Operation $operation, array $uriVariables = [], array $context = []): void
+    {
+        // You can add pre-write code here.
+
+        // Call the decorated processor's process method.
+        $writtenObject = $this->processor->process($data, $operation, $uriVariables, $context);
+
+        // You can add post-write code here.
+
+        return $writtenObject;
+    }
+}
+```
+
+Now decorate the `RespondProcessor` with the `CustomRespondProcessor` using Symfony or Laravel:
+
+### Symfony Processor Decoration
+
+With Symfony you can simply do that by adding the `#[AsDecorator]` attribute as following:
+
+```php
+namespace App\State;
+
+use ApiPlatform\State\ProcessorInterface;
+
+#[AsDecorator(decorates: 'api_platform.state.processor.respond_processor')]
+final class CustomRespondProcessor implements ProcessorInterface
+{
+    // ...
+}
+```
+
+or in the `services.yaml` by defining:
+
+```yaml
+# api/config/services.yaml
+services:
+    # ...
+    App\State\CustomRespondProcessor:
+        decorates: api_platform.state.processor.respond_processor
+```
+
+And that's it!
+
+### Laravel Processor Decoration
+```php
+<?php
+
+namespace App\Providers;
+
+use App\State\CustomRespondProcessor;
+use ApiPlatform\State\Processor\RespondProcessor;
+use Illuminate\Support\ServiceProvider;
+
+class AppServiceProvider extends ServiceProvider
+{
+    public function register(): void
+    {
+        $this->app->extend(RespondProcessor::class, function (RespondProcessor $respondProcessor) {
+            return new CustomRespondProcessor($respondProcessor);
+        });
+    }
+}
+```