feat(httpcache): introduce PurgeTagProviderInterface extension point

guillaumedelre · guillaumedelre · commit 851f135c9f62 · 2026-05-11T23:06:57.000+02:00
PurgeHttpCacheListener cannot invalidate sub-resource collection IRIs
such as /parents/{id}/children because it lacks the parent uri_variables
when processing the child entity. The new PurgeTagProviderInterface
lets users plug in custom tag collection strategies for these cases.

Symfony: services tagged api_platform.http_cache.purge_tag_provider are
injected automatically. Laravel: bind implementations and tag them with
PurgeTagProviderInterface::class via $app-&gt;tag().

Signed-off-by: Guillaume Delré &lt;delre.guillaume@gmail.com&gt;
diff --git a/src/HttpCache/PurgeTagProviderInterface.php b/src/HttpCache/PurgeTagProviderInterface.php
@@ -0,0 +1,29 @@
+<?php
+
+/*
+ * This file is part of the API Platform project.
+ *
+ * (c) Kévin Dunglas <dunglas@gmail.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace ApiPlatform\HttpCache;
+
+/**
+ * Collects extra HTTP cache tags to invalidate for a given entity.
+ *
+ * Implement this interface to invalidate sub-resource collection IRIs
+ * (e.g. /parents/{id}/children) that the built-in listener cannot resolve
+ * on its own because it lacks the parent uri_variables.
+ */
+interface PurgeTagProviderInterface
+{
+    /**
+     * @return iterable<string> additional cache tags to invalidate for $entity
+     */
+    public function getTagsForResource(object $entity): iterable;
+}
diff --git a/src/Laravel/Eloquent/ApiPlatformEventProvider.php b/src/Laravel/Eloquent/ApiPlatformEventProvider.php
@@ -14,6 +14,7 @@
 namespace ApiPlatform\Laravel\Eloquent;
 
 use ApiPlatform\HttpCache\PurgerInterface;
+use ApiPlatform\HttpCache\PurgeTagProviderInterface;
 use ApiPlatform\HttpCache\SouinPurger;
 use ApiPlatform\HttpCache\VarnishPurger;
 use ApiPlatform\HttpCache\VarnishXKeyPurger;
@@ -90,7 +91,8 @@ public function register(): void
             return new PurgeHttpCacheListener(
                 $app->make(PurgerInterface::class),
                 $app->make(IriConverterInterface::class),
-                $app->make(ResourceClassResolverInterface::class)
+                $app->make(ResourceClassResolverInterface::class),
+                $app->tagged(PurgeTagProviderInterface::class),
             );
         });
     }
diff --git a/src/Laravel/Eloquent/Listener/PurgeHttpCacheListener.php b/src/Laravel/Eloquent/Listener/PurgeHttpCacheListener.php
@@ -14,6 +14,7 @@
 namespace ApiPlatform\Laravel\Eloquent\Listener;
 
 use ApiPlatform\HttpCache\PurgerInterface;
+use ApiPlatform\HttpCache\PurgeTagProviderInterface;
 use ApiPlatform\Metadata\Exception\InvalidArgumentException;
 use ApiPlatform\Metadata\Exception\ItemNotFoundException;
 use ApiPlatform\Metadata\GetCollection;
@@ -28,10 +29,14 @@ final class PurgeHttpCacheListener
      */
     private array $tags = [];
 
+    /**
+     * @param iterable<PurgeTagProviderInterface> $purgeTagProviders
+     */
     public function __construct(
         private readonly PurgerInterface $purger,
         private readonly IriConverterInterface $iriConverter,
         private readonly ResourceClassResolverInterface $resourceClassResolver,
+        private readonly iterable $purgeTagProviders = [],
     ) {
     }
 
@@ -41,15 +46,19 @@ public function __construct(
     public function handleModelSaved(string $eventName, array $data): void
     {
         foreach ($data as $model) {
-            if (!$this->resourceClassResolver->isResourceClass($model::class)) {
-                return;
+            if ($this->resourceClassResolver->isResourceClass($model::class)) {
+                try {
+                    $this->tags[] = $this->iriConverter->getIriFromResource($model);
+                    $this->tags[] = $this->iriConverter->getIriFromResource($model::class, operation: new GetCollection(class: $model::class));
+                } catch (InvalidArgumentException|ItemNotFoundException $e) {
+                    // do nothing
+                }
             }
 
-            try {
-                $this->tags[] = $this->iriConverter->getIriFromResource($model);
-                $this->tags[] = $this->iriConverter->getIriFromResource($model::class, operation: new GetCollection(class: $model::class));
-            } catch (InvalidArgumentException|ItemNotFoundException $e) {
-                // do nothing
+            foreach ($this->purgeTagProviders as $provider) {
+                foreach ($provider->getTagsForResource($model) as $tag) {
+                    $this->tags[] = $tag;
+                }
             }
         }
     }
@@ -60,15 +69,19 @@ public function handleModelSaved(string $eventName, array $data): void
     public function handleModelDeleted(string $eventName, array $data): void
     {
         foreach ($data as $model) {
-            if (!$this->resourceClassResolver->isResourceClass($model::class)) {
-                return;
+            if ($this->resourceClassResolver->isResourceClass($model::class)) {
+                try {
+                    $this->tags[] = $this->iriConverter->getIriFromResource($model);
+                    $this->tags[] = $this->iriConverter->getIriFromResource($model::class, operation: new GetCollection(class: $model::class));
+                } catch (InvalidArgumentException|ItemNotFoundException $e) {
+                    // do nothing
+                }
             }
 
-            try {
-                $this->tags[] = $this->iriConverter->getIriFromResource($model);
-                $this->tags[] = $this->iriConverter->getIriFromResource($model::class, operation: new GetCollection(class: $model::class));
-            } catch (InvalidArgumentException|ItemNotFoundException $e) {
-                // do nothing
+            foreach ($this->purgeTagProviders as $provider) {
+                foreach ($provider->getTagsForResource($model) as $tag) {
+                    $this->tags[] = $tag;
+                }
             }
         }
     }
diff --git a/src/Symfony/Bundle/Resources/config/doctrine_orm_http_cache_purger.php b/src/Symfony/Bundle/Resources/config/doctrine_orm_http_cache_purger.php
@@ -26,6 +26,7 @@
             service('api_platform.property_accessor'),
             service('api_platform.object_mapper')->nullOnInvalid(),
             service('api_platform.object_mapper.metadata_factory')->nullOnInvalid(),
+            tagged_iterator('api_platform.http_cache.purge_tag_provider'),
         ])
         ->tag('doctrine.event_listener', ['event' => 'preUpdate'])
         ->tag('doctrine.event_listener', ['event' => 'onFlush'])
diff --git a/src/Symfony/Doctrine/EventListener/PurgeHttpCacheListener.php b/src/Symfony/Doctrine/EventListener/PurgeHttpCacheListener.php
@@ -14,6 +14,7 @@
 namespace ApiPlatform\Symfony\Doctrine\EventListener;
 
 use ApiPlatform\HttpCache\PurgerInterface;
+use ApiPlatform\HttpCache\PurgeTagProviderInterface;
 use ApiPlatform\Metadata\Exception\InvalidArgumentException;
 use ApiPlatform\Metadata\Exception\OperationNotFoundException;
 use ApiPlatform\Metadata\GetCollection;
@@ -45,12 +46,16 @@ final class PurgeHttpCacheListener
 
     private array $scheduledInsertions = [];
 
+    /**
+     * @param iterable<PurgeTagProviderInterface> $purgeTagProviders
+     */
     public function __construct(private readonly PurgerInterface $purger,
         private readonly IriConverterInterface $iriConverter,
         private readonly ResourceClassResolverInterface $resourceClassResolver,
         ?PropertyAccessorInterface $propertyAccessor = null,
         private readonly ?ObjectMapperInterface $objectMapper = null,
-        private readonly ?ObjectMapperMetadataFactoryInterface $objectMapperMetadata = null)
+        private readonly ?ObjectMapperMetadataFactoryInterface $objectMapperMetadata = null,
+        private readonly iterable $purgeTagProviders = [])
     {
         $this->propertyAccessor = $propertyAccessor ?? PropertyAccess::createPropertyAccessor();
     }
@@ -137,6 +142,12 @@ private function gatherResourceAndItemTags(object $entity, bool $purgeItem): voi
             } catch (OperationNotFoundException|InvalidArgumentException) {
             }
         }
+
+        foreach ($this->purgeTagProviders as $provider) {
+            foreach ($provider->getTagsForResource($entity) as $tag) {
+                $this->tags[$tag] = $tag;
+            }
+        }
     }
 
     private function gatherRelationTags(EntityManagerInterface $em, object $entity): void
diff --git a/src/Symfony/Tests/Doctrine/EventListener/PurgeHttpCacheListenerTest.php b/src/Symfony/Tests/Doctrine/EventListener/PurgeHttpCacheListenerTest.php
@@ -14,10 +14,12 @@
 namespace ApiPlatform\Symfony\Tests\Doctrine\EventListener;
 
 use ApiPlatform\HttpCache\PurgerInterface;
+use ApiPlatform\HttpCache\PurgeTagProviderInterface;
 use ApiPlatform\Metadata\Exception\InvalidArgumentException;
 use ApiPlatform\Metadata\Exception\ItemNotFoundException;
 use ApiPlatform\Metadata\GetCollection;
 use ApiPlatform\Metadata\IriConverterInterface;
+use ApiPlatform\Metadata\Operation;
 use ApiPlatform\Metadata\ResourceClassResolverInterface;
 use ApiPlatform\Metadata\UrlGeneratorInterface;
 use ApiPlatform\Symfony\Doctrine\EventListener\PurgeHttpCacheListener;
@@ -270,6 +272,54 @@ public function testAddTagsForCollection(): void
         $listener->postFlush();
     }
 
+    public function testPurgeTagProviders(): void
+    {
+        $dummy = new Dummy();
+        $dummy->setId(1);
+
+        $purger = $this->createMock(PurgerInterface::class);
+        $purger->expects($this->once())
+            ->method('purge')
+            ->with(['/dummies', '/dummies/1', '/parents/42/children']);
+
+        $iriConverter = $this->createStub(IriConverterInterface::class);
+        $iriConverter->method('getIriFromResource')
+            ->willReturnCallback(static function (object|string $resource, int $referenceType = UrlGeneratorInterface::ABS_PATH, ?Operation $operation = null, array $context = []): string {
+                if ($operation instanceof GetCollection) {
+                    return '/dummies';
+                }
+
+                return '/dummies/1';
+            });
+
+        $resourceClassResolver = $this->createStub(ResourceClassResolverInterface::class);
+        $resourceClassResolver->method('isResourceClass')->willReturn(true);
+
+        $classMetadata = new ClassMetadata(Dummy::class);
+        $classMetadata->associationMappings = [];
+
+        $em = $this->createStub(EntityManagerInterface::class);
+        $em->method('getClassMetadata')->willReturn($classMetadata);
+
+        $changeSet = [];
+        $eventArgs = new PreUpdateEventArgs($dummy, $em, $changeSet);
+
+        $provider = $this->createMock(PurgeTagProviderInterface::class);
+        $provider->expects($this->once())
+            ->method('getTagsForResource')
+            ->with($dummy)
+            ->willReturn(['/parents/42/children']);
+
+        $listener = new PurgeHttpCacheListener(
+            $purger,
+            $iriConverter,
+            $resourceClassResolver,
+            purgeTagProviders: [$provider],
+        );
+        $listener->preUpdate($eventArgs);
+        $listener->postFlush();
+    }
+
     public function testMappedResources(): void
     {
         $mappedEntity = new MappedEntity();
