diff --git a/core/performance.md b/core/performance.md index b554c814002..dbe705bb4c2 100644 --- a/core/performance.md +++ b/core/performance.md @@ -293,6 +293,84 @@ final class UserResourcesSubscriber implements EventSubscriberInterface } ``` +### Invalidating Additional Tags on Mutation + +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. 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: + +```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 (!$resource instanceof Child || null === $resource->getParent()) { + return []; + } + + yield '/parents/'.$resource->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 + +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: