feat(httpcache): introduce PurgeTagProviderInterface extension point

src/HttpCache/PurgeTagProviderInterface.php

@@ -0,0 +1,35 @@
+<?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 resource.
+ */
+interface PurgeTagProviderInterface
+{
+    /**
+     * @return iterable<string>
+     */
+    public function getTagsForInsert(object $resource): iterable;
+
+    /**
+     * @return iterable<string>
+     */
+    public function getTagsForUpdate(object $resource, object $previousResource): iterable;
+
+    /**
+     * @return iterable<string>
+     */
+    public function getTagsForDelete(object $resource): iterable;
+}

src/HttpCache/State/PurgeTagsProcessor.php

@@ -0,0 +1,65 @@
+<?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\State;
+
+use ApiPlatform\HttpCache\PurgerInterface;
+use ApiPlatform\HttpCache\PurgeTagProviderInterface;
+use ApiPlatform\Metadata\DeleteOperationInterface;
+use ApiPlatform\Metadata\Operation;
+use ApiPlatform\State\ProcessorInterface;
+
+final class PurgeTagsProcessor implements ProcessorInterface
+{
+    /**
+     * @param iterable<PurgeTagProviderInterface> $providers
+     */
+    public function __construct(
+        private readonly ProcessorInterface $decorated,
+        private readonly PurgerInterface $purger,
+        private readonly iterable $providers = [],
+    ) {
+    }
+
+    public function process(mixed $data, Operation $operation, array $uriVariables = [], array $context = []): mixed
+    {
+        $isDelete = $operation instanceof DeleteOperationInterface;
+        $previousData = $context['previous_data'] ?? null;
+        $resourceForDelete = $isDelete && \is_object($data) ? $data : null;
+
+        $result = $this->decorated->process($data, $operation, $uriVariables, $context);
+
+        $tags = [];
+        foreach ($this->providers as $provider) {
+            if ($isDelete && null !== $resourceForDelete) {
+                foreach ($provider->getTagsForDelete($resourceForDelete) as $tag) {
+                    $tags[$tag] = $tag;
+                }
+            } elseif (\is_object($previousData) && \is_object($result)) {
+                foreach ($provider->getTagsForUpdate($result, $previousData) as $tag) {
+                    $tags[$tag] = $tag;
+                }
+            } elseif (null === $previousData && \is_object($result)) {
+                foreach ($provider->getTagsForInsert($result) as $tag) {
+                    $tags[$tag] = $tag;
+                }
+            }
+        }
+
+        if ($tags) {
+            $this->purger->purge(array_values($tags));
+        }
+
+        return $result;
+    }
+}

src/HttpCache/Tests/State/PurgeTagsProcessorTest.php

@@ -0,0 +1,156 @@
+<?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\Tests\State;
+
+use ApiPlatform\HttpCache\PurgerInterface;
+use ApiPlatform\HttpCache\PurgeTagProviderInterface;
+use ApiPlatform\HttpCache\State\PurgeTagsProcessor;
+use ApiPlatform\Metadata\Delete;
+use ApiPlatform\Metadata\Patch;
+use ApiPlatform\Metadata\Post;
+use ApiPlatform\Metadata\Put;
+use ApiPlatform\State\ProcessorInterface;
+use PHPUnit\Framework\TestCase;
+
+class PurgeTagsProcessorTest extends TestCase
+{
+    public function testCallsGetTagsForInsertOnPost(): void
+    {
+        $resource = new \stdClass();
+
+        $decorated = $this->createStub(ProcessorInterface::class);
+        $decorated->method('process')->willReturn($resource);
+
+        $provider = $this->createMock(PurgeTagProviderInterface::class);
+        $provider->expects($this->once())->method('getTagsForInsert')->with($resource)->willReturn(['/parents/1/children']);
+        $provider->expects($this->never())->method('getTagsForUpdate');
+        $provider->expects($this->never())->method('getTagsForDelete');
+
+        $purger = $this->createMock(PurgerInterface::class);
+        $purger->expects($this->once())->method('purge')->with(['/parents/1/children']);
+
+        $processor = new PurgeTagsProcessor($decorated, $purger, [$provider]);
+        $processor->process($resource, new Post(), [], []);
+    }
+
+    public function testCallsGetTagsForUpdateOnPut(): void
+    {
+        $resource = new \stdClass();
+        $previousResource = new \stdClass();
+
+        $decorated = $this->createStub(ProcessorInterface::class);
+        $decorated->method('process')->willReturn($resource);
+
+        $provider = $this->createMock(PurgeTagProviderInterface::class);
+        $provider->expects($this->never())->method('getTagsForInsert');
+        $provider->expects($this->once())->method('getTagsForUpdate')->with($resource, $previousResource)->willReturn(['/parents/1/children', '/parents/2/children']);
+        $provider->expects($this->never())->method('getTagsForDelete');
+
+        $purger = $this->createMock(PurgerInterface::class);
+        $purger->expects($this->once())->method('purge')->with(['/parents/1/children', '/parents/2/children']);
+
+        $processor = new PurgeTagsProcessor($decorated, $purger, [$provider]);
+        $processor->process($resource, new Put(), [], ['previous_data' => $previousResource]);
+    }
+
+    public function testCallsGetTagsForUpdateOnPatch(): void
+    {
+        $resource = new \stdClass();
+        $previousResource = new \stdClass();
+
+        $decorated = $this->createStub(ProcessorInterface::class);
+        $decorated->method('process')->willReturn($resource);
+
+        $provider = $this->createMock(PurgeTagProviderInterface::class);
+        $provider->expects($this->once())->method('getTagsForUpdate')->with($resource, $previousResource)->willReturn(['/parents/1/children']);
+        $provider->expects($this->never())->method('getTagsForInsert');
+        $provider->expects($this->never())->method('getTagsForDelete');
+
+        $purger = $this->createMock(PurgerInterface::class);
+        $purger->expects($this->once())->method('purge')->with(['/parents/1/children']);
+
+        $processor = new PurgeTagsProcessor($decorated, $purger, [$provider]);
+        $processor->process($resource, new Patch(), [], ['previous_data' => $previousResource]);
+    }
+
+    public function testCallsGetTagsForDeleteOnDelete(): void
+    {
+        $resource = new \stdClass();
+
+        $decorated = $this->createStub(ProcessorInterface::class);
+        $decorated->method('process')->willReturn(null);
+
+        $provider = $this->createMock(PurgeTagProviderInterface::class);
+        $provider->expects($this->never())->method('getTagsForInsert');
+        $provider->expects($this->never())->method('getTagsForUpdate');
+        $provider->expects($this->once())->method('getTagsForDelete')->with($resource)->willReturn(['/parents/1/children']);
+
+        $purger = $this->createMock(PurgerInterface::class);
+        $purger->expects($this->once())->method('purge')->with(['/parents/1/children']);
+
+        $processor = new PurgeTagsProcessor($decorated, $purger, [$provider]);
+        $processor->process($resource, new Delete(), [], []);
+    }
+
+    public function testNoPurgeWhenNoTags(): void
+    {
+        $resource = new \stdClass();
+
+        $decorated = $this->createStub(ProcessorInterface::class);
+        $decorated->method('process')->willReturn($resource);
+
+        $provider = $this->createStub(PurgeTagProviderInterface::class);
+        $provider->method('getTagsForInsert')->willReturn([]);
+
+        $purger = $this->createMock(PurgerInterface::class);
+        $purger->expects($this->never())->method('purge');
+
+        $processor = new PurgeTagsProcessor($decorated, $purger, [$provider]);
+        $processor->process($resource, new Post(), [], []);
+    }
+
+    public function testDeduplicatesTags(): void
+    {
+        $resource = new \stdClass();
+
+        $decorated = $this->createStub(ProcessorInterface::class);
+        $decorated->method('process')->willReturn($resource);
+
+        $provider1 = $this->createStub(PurgeTagProviderInterface::class);
+        $provider1->method('getTagsForInsert')->willReturn(['/parents/1/children']);
+
+        $provider2 = $this->createStub(PurgeTagProviderInterface::class);
+        $provider2->method('getTagsForInsert')->willReturn(['/parents/1/children', '/parents/2/children']);
+
+        $purger = $this->createMock(PurgerInterface::class);
+        $purger->expects($this->once())->method('purge')->with(['/parents/1/children', '/parents/2/children']);
+
+        $processor = new PurgeTagsProcessor($decorated, $purger, [$provider1, $provider2]);
+        $processor->process($resource, new Post(), [], []);
+    }
+
+    public function testNoPurgeWhenNoProviders(): void
+    {
+        $resource = new \stdClass();
+
+        $decorated = $this->createStub(ProcessorInterface::class);
+        $decorated->method('process')->willReturn($resource);
+
+        $purger = $this->createMock(PurgerInterface::class);
+        $purger->expects($this->never())->method('purge');
+
+        $processor = new PurgeTagsProcessor($decorated, $purger, []);
+        $processor->process($resource, new Post(), [], []);
+    }
+}

src/Laravel/ApiPlatformDeferredProvider.php

@@ -20,6 +20,9 @@
 use ApiPlatform\GraphQl\Type\FieldsBuilderEnumInterface;
 use ApiPlatform\GraphQl\Type\TypeConverterInterface;
 use ApiPlatform\GraphQl\Type\TypesContainerInterface;
+use ApiPlatform\HttpCache\PurgerInterface;
+use ApiPlatform\HttpCache\PurgeTagProviderInterface;
+use ApiPlatform\HttpCache\State\PurgeTagsProcessor;
 use ApiPlatform\JsonApi\Filter\SparseFieldset;
 use ApiPlatform\JsonApi\Filter\SparseFieldsetParameterProvider;
 use ApiPlatform\Laravel\Controller\ApiPlatformController;
@@ -190,11 +193,25 @@ public function register(): void
                 $tagged['api_platform.swagger_ui.processor'] = $app->make(SwaggerUiProcessor::class);
             }
 
+            if (interface_exists(PurgerInterface::class) && $app->bound(PurgerInterface::class)) {
+                $purger = $app->make(PurgerInterface::class);
+                $providers = iterator_to_array($app->tagged(PurgeTagProviderInterface::class));
+                foreach ($tagged as $processor) {
+                    if ($processor instanceof PersistProcessor || $processor instanceof RemoveProcessor) {
+                        $tagged[$processor::class] = new PurgeTagsProcessor($processor, $purger, $providers);
+                    }
+                }
+            }
+
             return new CallableProcessor(new ServiceLocator($tagged));
         });
 
         $this->autoconfigure($classes, ProcessorInterface::class, [RemoveProcessor::class, PersistProcessor::class]);
 
+        if (interface_exists(PurgeTagProviderInterface::class)) {
+            $this->autoconfigure($classes, PurgeTagProviderInterface::class, []);
+        }
+
         $this->app->singleton(CallableProvider::class, static function (Application $app) {
             $tagged = iterator_to_array($app->tagged(ProviderInterface::class));
 

src/Laravel/Eloquent/ApiPlatformEventProvider.php

@@ -90,7 +90,7 @@ public function register(): void
             return new PurgeHttpCacheListener(
                 $app->make(PurgerInterface::class),
                 $app->make(IriConverterInterface::class),
-                $app->make(ResourceClassResolverInterface::class)
+                $app->make(ResourceClassResolverInterface::class),
             );
         });
     }

src/Laravel/Tests/MockPurgeTagProvider.php

@@ -0,0 +1,34 @@
+<?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\Laravel\Tests;
+
+use ApiPlatform\HttpCache\PurgeTagProviderInterface;
+
+class MockPurgeTagProvider implements PurgeTagProviderInterface
+{
+    public function getTagsForInsert(object $resource): iterable
+    {
+        return ['provider_insert'];
+    }
+
+    public function getTagsForUpdate(object $resource, object $previousResource): iterable
+    {
+        return ['provider_update'];
+    }
+
+    public function getTagsForDelete(object $resource): iterable
+    {
+        return ['provider_delete'];
+    }
+}