From 772ed349ff928d03683de42f60973015edb897b2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Guillaume=20Delr=C3=A9?= Date: Mon, 11 May 2026 23:13:06 +0200 Subject: [PATCH 1/4] docs(httpcache): document PurgeTagProviderInterface extension point MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Guillaume Delré --- core/performance.md | 53 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 53 insertions(+) diff --git a/core/performance.md b/core/performance.md index b554c814002..69faba913d4 100644 --- a/core/performance.md +++ b/core/performance.md @@ -293,6 +293,59 @@ final class UserResourcesSubscriber implements EventSubscriberInterface } ``` +### Invalidating Additional Tags on Mutation + +Implement `ApiPlatform\HttpCache\PurgeTagProviderInterface` to add extra cache tags to invalidate +when an entity is mutated. This is useful for any tags the built-in listener cannot resolve on its +own: sub-resource collection IRIs (e.g. `/parents/{parentId}/children`), surrogate-key prefixes, +class-based tags, or any custom invalidation strategy. + +```php +getParent()) { + return []; + } + + yield '/parents/'.$entity->getParent()->getId().'/children'; + } +} +``` + +#### Symfony + +With [autowiring and autoconfiguration](https://symfony.com/doc/current/service_container/autowiring.html) +enabled (the default), the service is automatically registered. To declare the service explicitly: + +```yaml +# config/services.yaml +services: + App\HttpCache\ChildPurgeTagProvider: + tags: + - name: api_platform.http_cache.purge_tag_provider +``` + +#### Laravel + +Register and tag the implementation in a service provider: + +```php +$this->app->bind(\App\HttpCache\ChildPurgeTagProvider::class); +$this->app->tag( + [\App\HttpCache\ChildPurgeTagProvider::class], + \ApiPlatform\HttpCache\PurgeTagProviderInterface::class +); +``` + ## Setting Custom HTTP Cache Headers The `cacheHeaders` attribute can be used to set custom HTTP cache headers: From f5c01d870748455bf96b77a899692c616b1b9b00 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Guillaume=20Delr=C3=A9?= Date: Tue, 19 May 2026 15:06:21 +0200 Subject: [PATCH 2/4] docs(httpcache): update PurgeTagProviderInterface example with per-operation methods Replace getTagsForResource() with the three dedicated methods (getTagsForInsert, getTagsForUpdate, getTagsForDelete) and show the parent-change invalidation use case that motivated the split. Drop the Laravel section (out of scope). --- core/performance.md | 44 ++++++++++++++++++++++++++++---------------- 1 file changed, 28 insertions(+), 16 deletions(-) diff --git a/core/performance.md b/core/performance.md index 69faba913d4..79ead2ae764 100644 --- a/core/performance.md +++ b/core/performance.md @@ -296,10 +296,13 @@ final class UserResourcesSubscriber implements EventSubscriberInterface ### Invalidating Additional Tags on Mutation Implement `ApiPlatform\HttpCache\PurgeTagProviderInterface` to add extra cache tags to invalidate -when an entity is mutated. This is useful for any tags the built-in listener cannot resolve on its +when a resource is mutated. This is useful for any tags the built-in listener cannot resolve on its own: sub-resource collection IRIs (e.g. `/parents/{parentId}/children`), surrogate-key prefixes, class-based tags, or any custom invalidation strategy. +The interface provides three methods so you can differentiate between operations and receive the +previous state of the resource on updates: + ```php getParent()) { + return []; + } + + yield '/parents/'.$resource->getParent()->getId().'/children'; + } + + public function getTagsForUpdate(object $resource, object $previousResource): iterable + { + // Invalidate both the old and new parent collection when the parent changes + if ($resource instanceof Child && null !== $resource->getParent()) { + yield '/parents/'.$resource->getParent()->getId().'/children'; + } + + if ($previousResource instanceof Child && null !== $previousResource->getParent()) { + yield '/parents/'.$previousResource->getParent()->getId().'/children'; + } + } + + public function getTagsForDelete(object $resource): iterable { - if (!$entity instanceof Child || null === $entity->getParent()) { + if (!$resource instanceof Child || null === $resource->getParent()) { return []; } - yield '/parents/'.$entity->getParent()->getId().'/children'; + yield '/parents/'.$resource->getParent()->getId().'/children'; } } ``` @@ -334,18 +358,6 @@ services: - name: api_platform.http_cache.purge_tag_provider ``` -#### Laravel - -Register and tag the implementation in a service provider: - -```php -$this->app->bind(\App\HttpCache\ChildPurgeTagProvider::class); -$this->app->tag( - [\App\HttpCache\ChildPurgeTagProvider::class], - \ApiPlatform\HttpCache\PurgeTagProviderInterface::class -); -``` - ## Setting Custom HTTP Cache Headers The `cacheHeaders` attribute can be used to set custom HTTP cache headers: From f19088e6140091b10f8f6c2387488db11c1afe93 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Guillaume=20Delr=C3=A9?= Date: Tue, 19 May 2026 15:34:10 +0200 Subject: [PATCH 3/4] docs(httpcache): add Laravel registration section for PurgeTagProviderInterface --- core/performance.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/core/performance.md b/core/performance.md index 79ead2ae764..20b26004f6a 100644 --- a/core/performance.md +++ b/core/performance.md @@ -358,6 +358,11 @@ services: - name: api_platform.http_cache.purge_tag_provider ``` +#### Laravel + +Any class implementing `PurgeTagProviderInterface` placed inside your `app/` directory is automatically +discovered and registered by API Platform's autoconfiguration. No further setup is required. + ## Setting Custom HTTP Cache Headers The `cacheHeaders` attribute can be used to set custom HTTP cache headers: From 3cea6b46aed9a07e432381edb4e0db5cfb27be38 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Guillaume=20Delr=C3=A9?= Date: Thu, 19 Nov 2026 09:37:43 +0100 Subject: [PATCH 4/4] docs(httpcache): document version and trigger conditions of purge tag providers --- core/performance.md | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/core/performance.md b/core/performance.md index 20b26004f6a..dbe705bb4c2 100644 --- a/core/performance.md +++ b/core/performance.md @@ -298,7 +298,13 @@ final class UserResourcesSubscriber implements EventSubscriberInterface Implement `ApiPlatform\HttpCache\PurgeTagProviderInterface` to add extra cache tags to invalidate when a resource is mutated. This is useful for any tags the built-in listener cannot resolve on its own: sub-resource collection IRIs (e.g. `/parents/{parentId}/children`), surrogate-key prefixes, -class-based tags, or any custom invalidation strategy. +class-based tags, or any custom invalidation strategy. This interface is available since API +Platform 5.1. + +> [!NOTE] Providers are called by the built-in Doctrine persist and remove state processors, after +> the resource has been persisted or removed. Changes flushed outside of an API Platform operation +> (for instance in a console command or a message handler), or by a custom state processor that does +> not delegate to the built-in ones, do not trigger them. The interface provides three methods so you can differentiate between operations and receive the previous state of the resource on updates: @@ -347,7 +353,8 @@ final class ChildPurgeTagProvider implements PurgeTagProviderInterface #### Symfony -With [autowiring and autoconfiguration](https://symfony.com/doc/current/service_container/autowiring.html) +With +[autowiring and autoconfiguration](https://symfony.com/doc/current/service_container/autowiring.html) enabled (the default), the service is automatically registered. To declare the service explicitly: ```yaml @@ -360,8 +367,9 @@ services: #### Laravel -Any class implementing `PurgeTagProviderInterface` placed inside your `app/` directory is automatically -discovered and registered by API Platform's autoconfiguration. No further setup is required. +Any class implementing `PurgeTagProviderInterface` placed inside your `app/` directory is +automatically discovered and registered by API Platform's autoconfiguration. No further setup is +required. ## Setting Custom HTTP Cache Headers