Skip to content
Open
Changes from all commits
Commits
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
78 changes: 78 additions & 0 deletions core/performance.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
<?php
// src/HttpCache/ChildPurgeTagProvider.php
namespace App\HttpCache;

use ApiPlatform\HttpCache\PurgeTagProviderInterface;
use App\Entity\Child;

final class ChildPurgeTagProvider implements PurgeTagProviderInterface
{
public function getTagsForInsert(object $resource): iterable
{
if (!$resource instanceof Child || null === $resource->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:
Expand Down
Loading