Skip to content

Commit d84cd2f

Browse files
vinceAmstoutzdunglassoyukaalanpoulain
authored
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]>
1 parent 4881e9e commit d84cd2f

File tree

3 files changed

+531
-259
lines changed

3 files changed

+531
-259
lines changed

‎core/events.md

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,13 @@
11
# The Event System
22

3-
In API Platform 3.2 you may need `event_listeners_backward_compatibility_layer: true` to keep event listeners activated.
3+
> [!WARNING]
4+
> In API Platform 4.0 with Symfony, you need `use_symfony_listeners: true` to activate event listeners.
45
5-
Note: using Kernel event with API Platform should be mostly limited to tweaking the generated HTTP response. Also, GraphQL is **not supported**.
6-
[For most use cases, better extension points, working both with REST and GraphQL, are available](extending.md).
6+
---
7+
8+
> [!NOTE]
9+
> Using Kernel event with API Platform should be mostly limited to tweaking the generated HTTP response. Also, GraphQL is **not supported**.
10+
> We recommend to use [System providers and processors](extending.md#system-providers-and-processors) to extend API Platform internals.
711
812
API Platform Core implements the [Action-Domain-Responder](https://github.com/pmjones/adr) pattern. This implementation
913
is covered in depth in the [Creating custom operations and controllers](operations.md#creating-custom-operations-and-controllers)

‎core/extending.md

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -36,3 +36,115 @@ For instance, if you want to send a mail after a resource has been persisted, bu
3636
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).
3737

3838
<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>
39+
40+
## System Providers and Processors
41+
42+
The system is based on a workflow composed of **state providers** and **state processors**.
43+
44+
The schema below describes them:
45+
46+
```mermaid
47+
---
48+
title: System providers and processors
49+
---
50+
flowchart TB
51+
C1(ReadProvider) --> C2(AccessCheckerProvider)
52+
C2 --> C3(DeserializeProvider)
53+
C3 --> C4(ParameterProvider)
54+
C4 --> C5(ValidateProcessor)
55+
C5 --> C6(WriteProcessor)
56+
C6 --> C7(SerializeProcessor)
57+
```
58+
59+
### Symfony Access Checker Provider
60+
61+
When using Symfony, the access checker provider is used at three different stages:
62+
- `api_platform.state_provider.access_checker.post_validate` decorates the `ValidateProvider`
63+
- `api_platform.state_provider.access_checker.post_deserialize` decorates the `DeserializeProvider`
64+
- `api_platform.state_provider.access_checker` decorates the `ReadProvider`
65+
66+
> [!NOTE]
67+
> For graphql use: `api_platform.graphql.state_provider.access_checker.post_deserialize`,
68+
> `api_platform.graphql.state_provider.access_checker.post_validate`, `api_platform.graphql.state_provider.validate` and
69+
> `api_platform.graphql.state_provider.access_checker.after_resolver`
70+
71+
### Decoration Example
72+
73+
Here is an example of the decoration of the RespondProcessor:
74+
75+
Starts by creating your `CustomRespondProcessor`:
76+
77+
```php
78+
<?php
79+
namespace App\State;
80+
81+
use ApiPlatform\State\ProcessorInterface;
82+
83+
final class CustomRespondProcessor implements ProcessorInterface
84+
{
85+
public function __construct(private readonly ProcessorInterface $processor) {}
86+
87+
public function process(mixed $data, Operation $operation, array $uriVariables = [], array $context = []): void
88+
{
89+
// You can add pre-write code here.
90+
91+
// Call the decorated processor's process method.
92+
$writtenObject = $this->processor->process($data, $operation, $uriVariables, $context);
93+
94+
// You can add post-write code here.
95+
96+
return $writtenObject;
97+
}
98+
}
99+
```
100+
101+
Now decorate the `RespondProcessor` with the `CustomRespondProcessor` using Symfony or Laravel:
102+
103+
### Symfony Processor Decoration
104+
105+
With Symfony you can simply do that by adding the `#[AsDecorator]` attribute as following:
106+
107+
```php
108+
namespace App\State;
109+
110+
use ApiPlatform\State\ProcessorInterface;
111+
112+
#[AsDecorator(decorates: 'api_platform.state.processor.respond_processor')]
113+
final class CustomRespondProcessor implements ProcessorInterface
114+
{
115+
// ...
116+
}
117+
```
118+
119+
or in the `services.yaml` by defining:
120+
121+
```yaml
122+
# api/config/services.yaml
123+
services:
124+
# ...
125+
App\State\CustomRespondProcessor:
126+
decorates: api_platform.state.processor.respond_processor
127+
```
128+
129+
And that's it!
130+
131+
### Laravel Processor Decoration
132+
```php
133+
<?php
134+
135+
namespace App\Providers;
136+
137+
use App\State\CustomRespondProcessor;
138+
use ApiPlatform\State\Processor\RespondProcessor;
139+
use Illuminate\Support\ServiceProvider;
140+
141+
class AppServiceProvider extends ServiceProvider
142+
{
143+
public function register(): void
144+
{
145+
$this->app->extend(RespondProcessor::class, function (RespondProcessor $respondProcessor) {
146+
return new CustomRespondProcessor($respondProcessor);
147+
});
148+
}
149+
}
150+
```

0 commit comments

Comments
 (0)