Merge remote-tracking branch 'upstream/2.6' into main

Author: vincentchalamon

core/jwt.md

@@ -120,7 +120,7 @@ security:
     # https://symfony.com/doc/current/security.html#c-hashing-passwords
     password_hashers:
         App\Entity\User: 'auto'
-    
+
     # https://symfony.com/doc/current/security/authenticator_manager.html
     enable_authenticator_manager: true
     # https://symfony.com/doc/current/security.html#where-do-users-come-from-user-providers
@@ -165,7 +165,7 @@ Want to test the routes of your JWT-authentication-protected API?
 api_platform:
     swagger:
          api_keys:
-             apiKey:
+             JWT:
                 name: Authorization
                 type: header
 ```
@@ -236,6 +236,13 @@ final class JwtDecorator implements OpenApiFactoryInterface
             ],
         ]);
 
+        $schemas = $openApi->getComponents()->getSecuritySchemes() ?? [];
+        $schemas['JWT'] = new ArrayObject([
+            'type' => 'http',
+            'scheme' => 'bearer',
+            'bearerFormat' => 'JWT',
+        ]);
+        
         $pathItem = new Model\PathItem(
             ref: 'JWT Token',
             post: new Model\Operation(
@@ -278,11 +285,11 @@ And register this service in `config/services.yaml`:
 ```yaml
 # api/config/services.yaml
 services:
-    # ...   
+    # ...
 
     App\OpenApi\JwtDecorator:
         decorates: 'api_platform.openapi.factory'
-        arguments: ['@.inner'] 
+        arguments: ['@.inner']
 ```
 
 ## Testing
@@ -306,14 +313,15 @@ class AuthenticationTest extends ApiTestCase
     public function testLogin(): void
     {
         $client = self::createClient();
+        $container = self::getContainer();
 
         $user = new User();
         $user->setEmail('test@example.com');
         $user->setPassword(
-            self::$container->get('security.user_password_hasher')->hashPassword($user, '$3CR3T')
+            $container->get('security.user_password_hasher')->hashPassword($user, '$3CR3T')
         );
 
-        $manager = self::$container->get('doctrine')->getManager();
+        $manager = $container->get('doctrine')->getManager();
         $manager->persist($user);
         $manager->flush();
 
@@ -349,7 +357,7 @@ Since now we have a `JWT` authentication, functional tests require us to log in
 
 Hashers are used for 2 reasons:
 
-1. To generate a hash for a raw password (`self::$container->get('security.user_password_hasher')->hashPassword($user, '$3CR3T')`)
+1. To generate a hash for a raw password (`$container->get('security.user_password_hasher')->hashPassword($user, '$3CR3T')`)
 2. To verify a password during authentication
 
 While hashing and verifying 1 password is quite a fast operation, doing it hundreds or even thousands of times in a tests suite becomes a bottleneck, because reliable hashing algorithms are slow by their nature.

core/openapi.md

@@ -447,7 +447,9 @@ Change `/docs` to the URI you wish Swagger to be accessible on.
 
 ## Using a custom Asset Package in Swagger UI
 
-Sometimes you may want to use a different [Asset Package](https://symfony.com/doc/current/reference/configuration/framework.html#packages) for the Swagger UI. In this way you'll have more fine-grained control over the asset url generations. This is useful i.e. if you want to use different base path, base url or asset versioning strategy.
+Sometimes you may want to use a different [Asset Package](https://symfony.com/doc/current/reference/configuration/framework.html#packages) for the Swagger UI.
+In this way you'll have more fine-grained control over the asset URL generations.
+This is useful i.e. if you want to use different base path, base URL or asset versioning strategy.
 
 Specify a custom asset package name:
 
@@ -485,15 +487,15 @@ As described [in the Symfony documentation](https://symfony.com/doc/current/temp
 </html>
 ```
 
-You may want to copy the [one shipped with API Platform](https://github.com/api-platform/core/blob/main/src/Bridge/Symfony/Bundle/Resources/views/SwaggerUi/index.html.twig) and customize it.
+You may want to copy the [one shipped with API Platform](https://github.com/api-platform/core/blob/2.6/src/Bridge/Symfony/Bundle/Resources/views/SwaggerUi/index.html.twig) and customize it.
 
 ## Compatibility Layer with Amazon API Gateway
 
 [AWS API Gateway](https://aws.amazon.com/api-gateway/) supports OpenAPI partially, but it [requires some changes](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-known-issues.html).
 API Platform provides a way to be compatible with Amazon API Gateway.
 
 To enable API Gateway compatibility on your OpenAPI docs, add `api_gateway=true` as query parameter: `http://www.example.com/docs.json?api_gateway=true`.
-The flag `--api-gateway` is also available through the command line.
+The flag `--api-gateway` is also available through the command-line.
 
 ## OAuth
 

core/push-relations.md

@@ -7,7 +7,7 @@
 API Platform leverages this capability by pushing relations of a resource to clients.
 
 **Note:** We strongly recommend using [Vulcain](https://vulcain.rocks) instead of this feature.
-Vulcain is faster, cleaner, more flexible, and is supported out of the box in the API Platform distribution.
+Vulcain is faster, cleaner, more flexible, and is supported out of the box in [the API Platform distribution](../distribution/index.md).
 
 ```php
 <?php
@@ -28,7 +28,10 @@ class Book
 ```
 
 By setting the `push` attribute to `true` on a property holding a relation, API Platform will automatically add a valid `Link` HTTP header with the `preload` relation.
-According to the [Preload W3C Candidate Recommendation](https://www.w3.org/TR/preload/), web servers and proxy servers can read this header, fetch the related resource and send it to the client using Server Push.
+According to the [Preload W3C Candidate Recommendation](https://www.w3.org/TR/preload/#server-push-http-2), web servers and proxy servers can read this header, fetch the related resource and send it to the client using Server Push.
+
+With the Caddy web server (the server shipped as part of the [distribution](../distribution/index.md)), you must add [the `push` directive](https://caddyserver.com/docs/caddyfile/directives/push) to your `Caddyfile` to be able to use this feature.
+
 [NGINX](https://www.nginx.com/blog/nginx-1-13-9-http2-server-push/), [Apache](https://httpd.apache.org/docs/current/howto/http2.html#push), [Cloudflare](https://www.cloudflare.com/website-optimization/http2/serverpush/), [Fastly](https://docs.fastly.com/guides/performance-tuning/http2-server-push) and [Akamai](https://blogs.akamai.com/2017/03/http2-server-push-the-what-how-and-why.html)
 honor this header.
 

core/serialization.md

@@ -696,7 +696,7 @@ class Book
     /**
      * This field can be managed only by an admin
      */
-    #[Groups(['book:output', 'admin:input'}])]
+    #[Groups(['book:output', 'admin:input'])]
     public bool $active = false;
 
     /**

core/validation.md

@@ -369,6 +369,89 @@ class Greeting
 }
 ```
 
+## Validating Delete Operations
+
+By default, validation rules that are specified on the API resource are not evaluated during DELETE operations. You need to trigger the validation in your code, if needed.
+
+Assume that you have the following entity that uses a custom delete validator:
+
+```php
+<?php
+// api/src/Entity/MyEntity.php
+
+namespace App\Entity;
+
+use ApiPlatform\Core\Annotation\ApiResource;
+use App\Validator\AssertCanDelete;
+use Doctrine\ORM\Mapping as ORM;
+
+#[ORM\Entity]
+#[ApiResource(
+    itemOperations: [
+      'delete' => [
+        'validation_groups' => ['deleteValidation']
+      ]
+    ]
+)]
+#[AssertCanDelete(groups: ['deleteValidation'])]
+class MyEntity
+{
+    #[ORM\Id, ORM\Column, ORM\GeneratedValue]
+    private ?int $id = null;
+
+    #[ORM\Column]
+    public string $name = '';
+}
+```
+
+Create a data persister, which decorates the default data persister, where you will trigger the validation:
+
+```php
+<?php
+// api/src/DataPersister/MyEntityDataPersister.php
+
+namespace App\DataPersister;
+
+use ApiPlatform\Core\DataPersister\DataPersisterInterface;
+use ApiPlatform\Core\Validator\ValidatorInterface;
+use App\Entity\MyEntity;
+
+class MyEntityDataPersister implements DataPersisterInterface
+{
+    public function __construct(
+        private DataPersisterInterface $decoratedDoctrineDataPersister,
+        private ValidatorInterface $validator,
+    ) {
+    }
+
+    public function persist($data): void {
+        $this->decoratedDoctrineDataPersister->persist($data);
+    }
+
+    public function remove($data): void {
+        $this->validator->validate(
+            $data,
+            ['groups' => ['deleteValidation']]
+        );
+        $this->decoratedDoctrineDataPersister->remove($data);
+    }
+
+    public function supports($data): bool {
+        return $data instanceof MyEntity;
+    }
+}
+```
+
+Register the new data persister in `api/config/services.yaml`:
+
+```yaml
+# api/config/services.yaml
+services:
+    _defaults:
+        bind:
+            $decoratedDoctrineDataPersister: '@api_platform.doctrine.orm.data_persister'
+```
+
 ## Error Levels and Payload Serialization
 
 As stated in the [Symfony documentation](https://symfony.com/doc/current/validation/severity.html), you can use the payload field to define error levels.

distribution/caddy.md

@@ -0,0 +1,35 @@
+# Configuring the Caddy Web Server
+
+[The API Platform distribution](index.md) is shipped with [the Caddy web server](https://caddyserver.com).
+The build contains the [Mercure](../core/mercure.md) and the [Vulcain](https://vulcain.rocks) Caddy modules.
+
+Caddy is positioned in front of the web API and of the Progressive Web App.
+It routes requests to either service depending on the value of the `Accept` HTTP header or the extension
+of the requested file.
+
+Using the same domain to serve the API and the PWA [improves performance by preventing unnecessary CORS preflight requests
+and encourages embracing the REST principles](https://dunglas.fr/2022/01/preventing-cors-preflight-requests-using-content-negotiation/).
+
+By default, requests having an `Accept` request header containing the `text/html` media type are routed to the Next.js application,
+except for some paths known to be resources served by the API (e.g. the Swagger UI documentation, static files provided by bundles...).
+Other requests are routed to the API.
+
+Sometimes, you may want to let the PHP application generate HTML responses.
+For instance, when you create your own Symfony controllers serving HTML pages,
+or when using bundles such as EasyAdmin or SonataAdmin.
+
+To do so, you have to tweak the rules used to route the requests.
+Open `api-platform/api/docker/caddy/Caddyfile` and modify the expression.
+You can use [any CEL (Common Expression Language) expression](https://caddyserver.com/docs/caddyfile/matchers#expression) supported by Caddy.
+
+For instance, if you want to route all requests to a path starting with `/admin` to the API, modify the existing expression like this:
+
+```patch
+# Matches requests for HTML documents, for static files and for Next.js files,
+# except for known API paths and paths with extensions handled by API Platform
+@pwa expression `(
+        {header.Accept}.matches("\\btext/html\\b")
+-        && !{path}.matches("(?i)(?:^/docs|^/graphql|^/bundles/|^/_profiler|^/_wdt|\\.(?:json|html$|csv$|ya?ml$|xml$))")
++        && !{path}.matches("(?i)(?:^/admin|^/docs|^/graphql|^/bundles/|^/_profiler|^/_wdt|\\.(?:json|html$|csv$|ya?ml$|xml$))")
+    )`
+```