Skip to content

feat(httpcache): introduce PurgeTagProviderInterface extension point #7970

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
guillaumedelre wants to merge 4 commits into
base: main
Choose a base branch
from
Open

feat(httpcache): introduce PurgeTagProviderInterface extension point #7970

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
88bd233
feat(httpcache): introduce PurgeTagProviderInterface extension point
guillaumedelre May 11, 2026
f9dd946
refactor(httpcache): rework PurgeTagProviderInterface with per-operat…
guillaumedelre May 19, 2026
23f166d
feat(httpcache): add Laravel support for PurgeTagProviderInterface
guillaumedelre May 19, 2026
7ad1afe
test(httpcache): add Laravel integration tests for PurgeTagProviderIn…
guillaumedelre May 19, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 25 additions & 0 deletions src/HttpCache/PurgeTagProviderInterface.php
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
<?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.
*/
interface PurgeTagProviderInterface
{
/**
* @return iterable<string>
*/
public function getTagsForResource(object $entity): iterable;
Copy link
Copy Markdown
Contributor

@usu usu May 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Shouldn't this method better receive both the old entity (before an update) and the new entity (after an update)? In the example provided in the initial issue, it will otherwise be difficult to detect when a child changes it's parent and hence 2 separate tags need to be purged?
Also providing old entity and new entity would provide an easy method for the provider to detect if the method was called from an insertion or deletion.

Copy link
Copy Markdown
Contributor Author

@guillaumedelre guillaumedelre May 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you for the feedback, you're right that the current signature is insufficient for the parent-change use case.

When a Child changes its parent, two tags need to be purged: /parents/{old_id}/children and /parents/{new_id}/children. With the current getTagsForResource(object $entity), the implementor only receives the entity in its new state and has no way to compute the old parent's tag.

The fix I have in mind is to change the signature to:

public function getTagsForResource(object $entity, ?object $previousEntity = null): iterable;

Where previousEntity is null on insertion and populated on update/deletion. This is BC-safe since the second parameter is nullable with a default value.

The key architectural point is where this is called. The current implementation calls providers from inside PurgeHttpCacheListener (a Doctrine ORM event listener). At that layer there is no previous_data — Doctrine's changeset only exposes scalar/identifier diffs, not a fully hydrated snapshot of the previous entity.

API Platform already solves this at a higher level: ReadProvider clones the entity before deserialization and stores it in $context['previous_data']. This snapshot is exactly what we need. The right place to call the providers is therefore the processor layer (e.g. PersistProcessor or a dedicated purge processor), where $context['previous_data'] is naturally available for PUT/PATCH operations and null for POST.

I can rework the PR to move the provider calls to that layer and update the interface accordingly. @soyuka what do you think?

Copy link
Copy Markdown
Contributor

@usu usu May 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, good point. We currently have an own implementation of the listener, where we use the Doctrine changeset to manually calculate the state of the previous entity. It works well for us, but cannot guarantee it is bulletproof:
https://github.com/ecamp/ecamp3/blob/6bebc1320d7f92bea8ecda743517632556b807a1/api/src/HttpCache/PurgeHttpCacheListener.php#L140C22-L140C39

Regarding the signature, shouldn't $entity also be nullable in case of deletions? In that case the provider could distinguish all 3 cases (updates, deletions, inserts) based on which parameter is null or populated.

Copy link
Copy Markdown
Contributor Author

@guillaumedelre guillaumedelre May 19, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There's an architectural constraint worth surfacing here. The providers are currently called from inside the Doctrine event listener, which operates at the ORM layer — it has no access to API Platform's request context. That means $previousResource cannot be populated on updates from that layer: Doctrine only exposes getEntityChangeSet() (scalar diffs), not a fully hydrated snapshot of the previous entity.

Two options:

Option 1 — keep providers in the listener, add array $context = []

public function getTagsForResource(object $resource, ?object $previousResource = null, array $context = []): iterable;

The listener only knows the Doctrine event type, so $context would carry a string at best:

$provider->getTagsForResource($entity, null, ['operation_type' => 'update']);

$previousResource would always be null on updates, defeating the purpose.

Option 2 — move provider calls to the processor layer

PersistProcessor has $context['previous_data'] natively (a full hydrated snapshot set by ReadProvider), and the actual API Platform Operation object as a dedicated parameter. Both can be forwarded to the provider:

// POST:   ($data, null,                          ['operation' => $operation, ...])
// PUT:    ($data, $context['previous_data'],      ['operation' => $operation, ...])
// DELETE: ($data, $context['previous_data'],      ['operation' => $operation, ...])

This is the only way to get a real $previousResource on updates, plus a typed Operation instance (e.g. Put, Delete) instead of a plain string. The catch: IRI isn't available before flush on inserts (no auto-generated ID yet), which the current listener handles via $scheduledInsertions + postFlush() — a complementary post-flush listener would still be needed for that case.

Option 2 gives the interface you described, at the cost of a broader refactor. Happy to go that route — wanted to flag the tradeoff first. What do you think?

Copy link
Copy Markdown
Contributor

@mrossard mrossard May 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nitpicking : if it's getTagsForResource, it should be called $resource, not $entity, shouldn't it?

That said I likely would have split methods for different operations, I agree with @usu that you're possibly not invalidating the same tags when inserting / modifying / deleting...but the caller should know which case they're in so why not just let the caller use the correct method?
It would imply some refactoring in the Doctrine event listener, but it would be for the best IMO.

Copy link
Copy Markdown
Contributor Author

@guillaumedelre guillaumedelre May 19, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agreed, renaming to $resource.

Regarding splitting into separate methods: the single-method approach with a nullable $previousResource is consistent with how the rest of the codebase handles this. ProcessorInterface::process() is a single method regardless of the HTTP operation, and PersistProcessor already uses $context['previous_data'] === null to distinguish INSERT from UPDATE. Splitting into three methods would also require three separate tagged iterables in the DI container, adding complexity without a clear gain here.

Copy link
Copy Markdown
Contributor

@mrossard mrossard May 19, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm probably missing something, but i don't see how having 3 methods in the PurgeTagProviderInterface would change anything for DI.
How would you differentiate between delete and update if you only rely on previous data? There is previous data in both cases, but you might not want to invalidate the same tags.

Copy link
Copy Markdown
Contributor Author

@guillaumedelre guillaumedelre May 19, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm probably missing something, but i don't see how having 3 methods in the PurgeTagProviderInterface would change anything for DI.

You're right, my DI argument was wrong. Apologies.

How would you differentiate between delete and update if you only rely on previous data?

Agreed, and that also pointed to a deeper issue: splitting the calls between the listener and a processor was the wrong architecture. Moving everything to the processor layer is cleaner.

PersistProcessor has both $context['previous_data'] (null on POST, populated on PUT/PATCH) and calls flush() + refresh() before returning, so the auto-generated ID is available before any provider call. RemoveProcessor similarly calls flush() before returning, with $data still in memory. A processor decorator can call all three methods from a single place.

The listener keeps its existing logic (collection IRI, item IRI, relations). The providers, as an extension point, belong in the processor layer where the context is richer.

So the interface becomes:

public function getTagsForInsert(object $resource): iterable;
public function getTagsForUpdate(object $resource, object $previousResource): iterable;
public function getTagsForDelete(object $resource): iterable;

Called from a PurgeTagsProcessor decorator that wraps PersistProcessor / RemoveProcessor. I'll rework the PR along these lines.

}
4 changes: 3 additions & 1 deletion src/Laravel/Eloquent/ApiPlatformEventProvider.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down Expand Up @@ -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),
);
});
}
Expand Down
41 changes: 27 additions & 14 deletions src/Laravel/Eloquent/Listener/PurgeHttpCacheListener.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand All @@ -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 = [],
) {
}

Expand All @@ -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;
}
}
}
}
Expand All @@ -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;
}
}
}
}
Expand Down
114 changes: 114 additions & 0 deletions src/Laravel/Tests/Unit/Listener/PurgeHttpCacheListenerTest.php
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,114 @@
<?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\Unit\Listener;

use ApiPlatform\HttpCache\PurgerInterface;
use ApiPlatform\HttpCache\PurgeTagProviderInterface;
use ApiPlatform\Laravel\Eloquent\Listener\PurgeHttpCacheListener;
use ApiPlatform\Metadata\Exception\InvalidArgumentException;
use ApiPlatform\Metadata\GetCollection;
use ApiPlatform\Metadata\IriConverterInterface;
use ApiPlatform\Metadata\ResourceClassResolverInterface;
use Illuminate\Database\Eloquent\Model;
use PHPUnit\Framework\TestCase;

class PurgeHttpCacheListenerTest extends TestCase
{
public function testPurgeTagProviders(): void
{
$model = new class extends Model {
};

$purger = $this->createMock(PurgerInterface::class);
$purger->expects($this->once())
->method('purge')
->with(['/models/1', '/models', '/parents/42/children']);

$iriConverter = $this->createStub(IriConverterInterface::class);
$iriConverter->method('getIriFromResource')
->willReturnCallback(static function (object|string $resource, int $referenceType = 0, ?object $operation = null): string {
if ($operation instanceof GetCollection) {
return '/models';
}

return '/models/1';
});

$resourceClassResolver = $this->createStub(ResourceClassResolverInterface::class);
$resourceClassResolver->method('isResourceClass')->willReturn(true);

$provider = $this->createMock(PurgeTagProviderInterface::class);
$provider->expects($this->once())
->method('getTagsForResource')
->with($model)
->willReturn(['/parents/42/children']);

$listener = new PurgeHttpCacheListener($purger, $iriConverter, $resourceClassResolver, [$provider]);
$listener->handleModelSaved('eloquent.saved: '.$model::class, [$model]);
$listener->postFlush();
}

public function testPurgeTagProvidersOnDelete(): void
{
$model = new class extends Model {
};

$purger = $this->createMock(PurgerInterface::class);
$purger->expects($this->once())
->method('purge')
->with(['/models/1', '/models', '/parents/42/children']);

$iriConverter = $this->createStub(IriConverterInterface::class);
$iriConverter->method('getIriFromResource')
->willReturnCallback(static function (object|string $resource, int $referenceType = 0, ?object $operation = null): string {
if ($operation instanceof GetCollection) {
return '/models';
}

return '/models/1';
});

$resourceClassResolver = $this->createStub(ResourceClassResolverInterface::class);
$resourceClassResolver->method('isResourceClass')->willReturn(true);

$provider = $this->createMock(PurgeTagProviderInterface::class);
$provider->expects($this->once())
->method('getTagsForResource')
->with($model)
->willReturn(['/parents/42/children']);

$listener = new PurgeHttpCacheListener($purger, $iriConverter, $resourceClassResolver, [$provider]);
$listener->handleModelDeleted('eloquent.deleted: '.$model::class, [$model]);
$listener->postFlush();
}

public function testNoTagsWhenNoProviders(): void
{
$model = new class extends Model {
};

$purger = $this->createMock(PurgerInterface::class);
$purger->expects($this->never())->method('purge');

$iriConverter = $this->createStub(IriConverterInterface::class);
$iriConverter->method('getIriFromResource')->willThrowException(new InvalidArgumentException());

$resourceClassResolver = $this->createStub(ResourceClassResolverInterface::class);
$resourceClassResolver->method('isResourceClass')->willReturn(true);

$listener = new PurgeHttpCacheListener($purger, $iriConverter, $resourceClassResolver);
$listener->handleModelSaved('eloquent.saved: '.$model::class, [$model]);
$listener->postFlush();
}
}
3 changes: 3 additions & 0 deletions src/Symfony/Bundle/DependencyInjection/ApiPlatformExtension.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,7 @@
use ApiPlatform\GraphQl\Resolver\QueryCollectionResolverInterface;
use ApiPlatform\GraphQl\Resolver\QueryItemResolverInterface;
use ApiPlatform\GraphQl\Type\Definition\TypeInterface as GraphQlTypeInterface;
use ApiPlatform\HttpCache\PurgeTagProviderInterface;
use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Metadata\AsOperationMutator;
use ApiPlatform\Metadata\AsResourceMutator;
Expand Down Expand Up @@ -228,6 +229,8 @@ public function load(array $configs, ContainerBuilder $container): void
->addTag('api_platform.uri_variables.transformer');
$container->registerForAutoconfiguration(ParameterProviderInterface::class)
->addTag('api_platform.parameter_provider');
$container->registerForAutoconfiguration(PurgeTagProviderInterface::class)
->addTag('api_platform.http_cache.purge_tag_provider');

$container->registerAttributeForAutoconfiguration(
AsResourceMutator::class,
Expand Down
1 change: 1 addition & 0 deletions src/Symfony/Bundle/Resources/config/doctrine_orm_http_cache_purger.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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'])
Expand Down
13 changes: 12 additions & 1 deletion src/Symfony/Doctrine/EventListener/PurgeHttpCacheListener.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down Expand Up @@ -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();
}
Expand Down Expand Up @@ -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
Expand Down
54 changes: 54 additions & 0 deletions src/Symfony/Tests/Doctrine/EventListener/PurgeHttpCacheListenerTest.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down Expand Up @@ -270,6 +272,58 @@ public function testAddTagsForCollection(): void
$listener->postFlush();
}

public function testPurgeTagProviders(): void
{
if (!interface_exists(PurgeTagProviderInterface::class)) {
$this->markTestSkipped('PurgeTagProviderInterface not available in installed api-platform/http-cache version.');
}

$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();
Expand Down
Loading