feat(performance): add Souin setup to the documentation (#1914)

core/performance.md

@@ -20,6 +20,63 @@ cache. This ensures that the content served will always be fresh, because the ca
 most specific cases such as the invalidation of collections when a document is added or removed or for relationships and
 inverse relations is built-in.
 
+### Integrations
+
+#### Built-in Caddy HTTP cache
+
+The API Platform distribution relies on the [Caddy web server](https://caddyserver.com) which provide an official HTTP cache module called [cache-handler](https://github.com/caddyserver/cache-handler), that is based on [Souin](https://github.com/darkweak/souin).
+
+The integration using the cache-handler is quite simple. You juste have to update the `api/Dockerfile` to build your caddy instance with the HTTP cache
+
+```diff
+# Versions
+-FROM dunglas/frankenphp:1-php8.3 AS frankenphp_upstream
+
++FROM dunglas/frankenphp:latest-builder AS builder
++COPY --from=caddy:builder /usr/bin/xcaddy /usr/bin/xcaddy
++
++ENV CGO_ENABLED=1 XCADDY_SETCAP=1 XCADDY_GO_BUILD_FLAGS="-ldflags \"-w -s -extldflags '-Wl,-z,stack-size=0x80000'\""
++RUN xcaddy build \
++    --output /usr/local/bin/frankenphp \
++    --with github.com/dunglas/frankenphp=./ \
++    --with github.com/dunglas/frankenphp/caddy=./caddy/ \
++    --with github.com/dunglas/mercure/caddy \
++    --with github.com/dunglas/vulcain/caddy \
++    # Use --with github.com/darkweak/souin for the latest improvements
++    --with github.com/caddyserver/cache-handler
++
++FROM dunglas/frankenphp:latest AS frankenphp_upstream
++COPY --from=builder --link /usr/local/bin/frankenphp /usr/local/bin/frankenphp
+```
+
+Update your Caddyfile with the following configuration:
+```caddyfile
+{
+    order cache before rewrite
+    ...
+    cache {
+        api {
+            souin
+        }
+    }
+}
+```
+This will tell to caddy to use the HTTP cache and activate the tag based invalidation API. You can refer to the [cache-handler documentation](https://github.com/caddyserver/cache-handler) or the [souin website documentation](https://docs.souin.io) to learn how to configure the HTTP cache server.
+
+Setup the HTTP cache invalidation in your API Platform project
+```yaml
+api_platform:
+    http_cache:
+        invalidation:
+            # We assume that your API can reach your caddy instance by the hostname http://caddy.
+            # The endpoint /souin-api/souin is the default path to the invalidation API.
+            urls: [ 'http://caddy/souin-api/souin' ]
+            purger: api_platform.http_cache.purger.souin
+```
+And voilà, you have a fully working HTTP cache with it's own invalidation API.
+
+#### Varnish
+
 Integration with Varnish and Doctrine ORM is shipped with the core library.
 
 Add the following configuration to enable the cache invalidation system:
@@ -38,8 +95,9 @@ api_platform:
             vary: ['Content-Type', 'Authorization', 'Origin']
 ```
 
-Support for reverse proxies other than Varnish can be added by implementing the `ApiPlatform\HttpCache\PurgerInterface`.
-Two purgers are available, the http tags (`api_platform.http_cache.purger.varnish.ban`) or the surrogate key implementation
+## Configuration
+Support for reverse proxies other than Varnish or Caddy with the HTTP cache module can be added by implementing the `ApiPlatform\HttpCache\PurgerInterface`.
+Three purgers are available, the built-in caddy http cache purger (`api_platform.http_cache.purger.souin`), the http tags (`api_platform.http_cache.purger.varnish.ban`), the surrogate key implementation
 (`api_platform.http_cache.purger.varnish.xkey`). You can specify the implementation using the `purger` configuration node,
 for example to use the xkey implementation: