feat(serializer): collect cache tags using a TagCollector

.github/workflows/ci.yml

@@ -992,7 +992,7 @@ jobs:
       - name: Clear test app cache
         run: tests/Fixtures/app/console cache:clear --ansi
       - name: Run Behat tests
-        run: vendor/bin/behat --out=std --format=progress --profile=default --no-interaction
+        run: vendor/bin/behat --out=std --format=progress --profile=default --no-interaction --tags='~@disableForSymfonyLowest'
 
   phpunit_legacy:
     name: PHPUnit Legacy event listeners (PHP ${{ matrix.php }})

features/http_cache/tag_collector_service.feature

@@ -0,0 +1,56 @@
+@sqlite
+@customTagCollector
+@disableForSymfonyLowest
+Feature: Cache invalidation through HTTP Cache tags (custom TagCollector service)
+  In order to have a fast API
+  As an API software developer
+  I need to store API responses in a cache
+
+  @createSchema
+  Scenario: Create a dummy resource
+    When I add "Content-Type" header equal to "application/ld+json"
+    And I send a "POST" request to "/relation_embedders" with body:
+    """
+    {
+    }
+    """
+    Then the response status code should be 201
+    And the header "Cache-Tags" should not exist
+
+  Scenario: TagCollector can identify $object (IRI is overriden with custom logic)
+    When I send a "GET" request to "/relation_embedders/1"
+    Then the response status code should be 200
+    And the header "Cache-Tags" should be equal to "/RE/1#anotherRelated,/RE/1#related,/RE/1"
+
+  Scenario: Create some embedded resources
+    When I add "Content-Type" header equal to "application/ld+json"
+    And I send a "POST" request to "/relation_embedders" with body:
+    """
+    {
+      "anotherRelated": {
+        "name": "Related"
+      }
+    }
+    """
+    Then the response status code should be 201
+    And the header "Cache-Tags" should not exist
+
+  Scenario: TagCollector can add cache tags for relations
+    When I send a "GET" request to "/relation_embedders/2"
+    Then the response status code should be 200
+    And the header "Cache-Tags" should be equal to "/related_dummies/1#thirdLevel,/related_dummies/1,/RE/2#anotherRelated,/RE/2#related,/RE/2"
+
+  Scenario: Create resource with extraProperties on ApiProperty
+    When I add "Content-Type" header equal to "application/ld+json"
+    And I send a "POST" request to "/extra_properties_on_properties" with body:
+    """
+    {
+    }
+    """
+    Then the response status code should be 201
+    And the header "Cache-Tags" should not exist
+
+  Scenario: TagCollector can read propertyMetadata (tag is overriden with data from extraProperties)
+    When I send a "GET" request to "/extra_properties_on_properties/1"
+    Then the response status code should be 200
+    And the header "Cache-Tags" should be equal to "/extra_properties_on_properties/1#overrideRelationTag,/extra_properties_on_properties/1"

features/http_cache/tags.feature

@@ -23,7 +23,7 @@ Feature: Cache invalidation through HTTP Cache tags
   Scenario: Tags must be set for items
     When I send a "GET" request to "/relation_embedders/1"
     Then the response status code should be 200
-    And the header "Cache-Tags" should be equal to "/relation_embedders/1,/related_dummies/1,/third_levels/1"
+    And the header "Cache-Tags" should be equal to "/third_levels/1,/related_dummies/1,/relation_embedders/1"
 
   Scenario: Create some more resources
     When I add "Content-Type" header equal to "application/ld+json"
@@ -42,7 +42,7 @@ Feature: Cache invalidation through HTTP Cache tags
   Scenario: Tags must be set for collections
     When I send a "GET" request to "/relation_embedders"
     Then the response status code should be 200
-    And the header "Cache-Tags" should be equal to "/relation_embedders/1,/related_dummies/1,/third_levels/1,/relation_embedders/2,/related_dummies/2,/third_levels/2,/relation_embedders"
+    And the header "Cache-Tags" should be equal to "/third_levels/1,/related_dummies/1,/relation_embedders/1,/third_levels/2,/related_dummies/2,/relation_embedders/2,/relation_embedders"
 
   Scenario: Purge item on update
     When I add "Content-Type" header equal to "application/ld+json"
@@ -119,7 +119,7 @@ Feature: Cache invalidation through HTTP Cache tags
     When I add "Content-Type" header equal to "application/ld+json"
     And I send a "GET" request to "/relation3s"
     Then the response status code should be 200
-    And the header "Cache-Tags" should be equal to "/relation3s/1,/relation2s/1,/relation2s/2,/relation3s"
+    And the header "Cache-Tags" should be equal to "/relation2s/1,/relation2s/2,/relation3s/1,/relation3s"
 
   Scenario: Update a collection member only (legacy non-standard PUT)
     When I add "Content-Type" header equal to "application/ld+json"

src/JsonApi/Serializer/ItemNormalizer.php

@@ -27,6 +27,7 @@
 use ApiPlatform\Serializer\AbstractItemNormalizer;
 use ApiPlatform\Serializer\CacheKeyTrait;
 use ApiPlatform\Serializer\ContextTrait;
+use ApiPlatform\Serializer\TagCollectorInterface;
 use ApiPlatform\Symfony\Security\ResourceAccessCheckerInterface;
 use Symfony\Component\ErrorHandler\Exception\FlattenException;
 use Symfony\Component\PropertyAccess\PropertyAccessorInterface;
@@ -55,9 +56,9 @@ final class ItemNormalizer extends AbstractItemNormalizer
 
     private array $componentsCache = [];
 
-    public function __construct(PropertyNameCollectionFactoryInterface $propertyNameCollectionFactory, PropertyMetadataFactoryInterface $propertyMetadataFactory, IriConverterInterface|LegacyIriConverterInterface $iriConverter, ResourceClassResolverInterface|LegacyResourceClassResolverInterface $resourceClassResolver, PropertyAccessorInterface $propertyAccessor = null, NameConverterInterface $nameConverter = null, ClassMetadataFactoryInterface $classMetadataFactory = null, array $defaultContext = [], ResourceMetadataCollectionFactoryInterface $resourceMetadataCollectionFactory = null, ResourceAccessCheckerInterface $resourceAccessChecker = null)
+    public function __construct(PropertyNameCollectionFactoryInterface $propertyNameCollectionFactory, PropertyMetadataFactoryInterface $propertyMetadataFactory, IriConverterInterface|LegacyIriConverterInterface $iriConverter, ResourceClassResolverInterface|LegacyResourceClassResolverInterface $resourceClassResolver, PropertyAccessorInterface $propertyAccessor = null, NameConverterInterface $nameConverter = null, ClassMetadataFactoryInterface $classMetadataFactory = null, array $defaultContext = [], ResourceMetadataCollectionFactoryInterface $resourceMetadataCollectionFactory = null, ResourceAccessCheckerInterface $resourceAccessChecker = null, protected ?TagCollectorInterface $tagCollector = null)
     {
-        parent::__construct($propertyNameCollectionFactory, $propertyMetadataFactory, $iriConverter, $resourceClassResolver, $propertyAccessor, $nameConverter, $classMetadataFactory, $defaultContext, $resourceMetadataCollectionFactory, $resourceAccessChecker);
+        parent::__construct($propertyNameCollectionFactory, $propertyMetadataFactory, $iriConverter, $resourceClassResolver, $propertyAccessor, $nameConverter, $classMetadataFactory, $defaultContext, $resourceMetadataCollectionFactory, $resourceAccessChecker, $tagCollector);
     }
 
     /**
@@ -245,7 +246,7 @@ protected function normalizeRelation(ApiProperty $propertyMetadata, ?object $rel
             $iri = $this->iriConverter->getIriFromResource($relatedObject);
             $context['iri'] = $iri;
 
-            if (isset($context['resources'])) {
+            if (!$this->tagCollector && isset($context['resources'])) {
                 $context['resources'][$iri] = $iri;
             }
         }
@@ -263,12 +264,23 @@ protected function normalizeRelation(ApiProperty $propertyMetadata, ?object $rel
             return $normalizedRelatedObject;
         }
 
-        return [
+        $context['data'] = [
             'data' => [
                 'type' => $this->getResourceShortName($resourceClass),
                 'id' => $iri,
             ],
         ];
+
+        $context['iri'] = $iri;
+        $context['object'] = $relatedObject;
+        unset($context['property_metadata']);
+        unset($context['api_attribute']);
+
+        if ($this->tagCollector) {
+            $this->tagCollector->collect($context);
+        }
+
+        return $context['data'];
     }
 
     /**

src/JsonLd/Serializer/ItemNormalizer.php

@@ -27,6 +27,7 @@
 use ApiPlatform\Metadata\Util\ClassInfoTrait;
 use ApiPlatform\Serializer\AbstractItemNormalizer;
 use ApiPlatform\Serializer\ContextTrait;
+use ApiPlatform\Serializer\TagCollectorInterface;
 use ApiPlatform\Symfony\Security\ResourceAccessCheckerInterface;
 use Symfony\Component\PropertyAccess\PropertyAccessorInterface;
 use Symfony\Component\Serializer\Exception\LogicException;
@@ -47,9 +48,9 @@ final class ItemNormalizer extends AbstractItemNormalizer
 
     public const FORMAT = 'jsonld';
 
-    public function __construct(ResourceMetadataCollectionFactoryInterface $resourceMetadataCollectionFactory, PropertyNameCollectionFactoryInterface $propertyNameCollectionFactory, PropertyMetadataFactoryInterface $propertyMetadataFactory, IriConverterInterface|LegacyIriConverterInterface $iriConverter, ResourceClassResolverInterface|LegacyResourceClassResolverInterface $resourceClassResolver, private readonly ContextBuilderInterface $contextBuilder, PropertyAccessorInterface $propertyAccessor = null, NameConverterInterface $nameConverter = null, ClassMetadataFactoryInterface $classMetadataFactory = null, array $defaultContext = [], ResourceAccessCheckerInterface $resourceAccessChecker = null)
+    public function __construct(ResourceMetadataCollectionFactoryInterface $resourceMetadataCollectionFactory, PropertyNameCollectionFactoryInterface $propertyNameCollectionFactory, PropertyMetadataFactoryInterface $propertyMetadataFactory, IriConverterInterface|LegacyIriConverterInterface $iriConverter, ResourceClassResolverInterface|LegacyResourceClassResolverInterface $resourceClassResolver, private readonly ContextBuilderInterface $contextBuilder, PropertyAccessorInterface $propertyAccessor = null, NameConverterInterface $nameConverter = null, ClassMetadataFactoryInterface $classMetadataFactory = null, array $defaultContext = [], ResourceAccessCheckerInterface $resourceAccessChecker = null, protected ?TagCollectorInterface $tagCollector = null)
     {
-        parent::__construct($propertyNameCollectionFactory, $propertyMetadataFactory, $iriConverter, $resourceClassResolver, $propertyAccessor, $nameConverter, $classMetadataFactory, $defaultContext, $resourceMetadataCollectionFactory, $resourceAccessChecker);
+        parent::__construct($propertyNameCollectionFactory, $propertyMetadataFactory, $iriConverter, $resourceClassResolver, $propertyAccessor, $nameConverter, $classMetadataFactory, $defaultContext, $resourceMetadataCollectionFactory, $resourceAccessChecker, $tagCollector);
     }
 
     /**

src/Serializer/AbstractItemNormalizer.php

@@ -63,7 +63,7 @@ abstract class AbstractItemNormalizer extends AbstractObjectNormalizer
     protected array $localCache = [];
     protected array $localFactoryOptionsCache = [];
 
-    public function __construct(protected PropertyNameCollectionFactoryInterface $propertyNameCollectionFactory, protected PropertyMetadataFactoryInterface $propertyMetadataFactory, protected LegacyIriConverterInterface|IriConverterInterface $iriConverter, protected LegacyResourceClassResolverInterface|ResourceClassResolverInterface $resourceClassResolver, PropertyAccessorInterface $propertyAccessor = null, NameConverterInterface $nameConverter = null, ClassMetadataFactoryInterface $classMetadataFactory = null, array $defaultContext = [], ResourceMetadataCollectionFactoryInterface $resourceMetadataCollectionFactory = null, protected ?ResourceAccessCheckerInterface $resourceAccessChecker = null)
+    public function __construct(protected PropertyNameCollectionFactoryInterface $propertyNameCollectionFactory, protected PropertyMetadataFactoryInterface $propertyMetadataFactory, protected LegacyIriConverterInterface|IriConverterInterface $iriConverter, protected LegacyResourceClassResolverInterface|ResourceClassResolverInterface $resourceClassResolver, PropertyAccessorInterface $propertyAccessor = null, NameConverterInterface $nameConverter = null, ClassMetadataFactoryInterface $classMetadataFactory = null, array $defaultContext = [], ResourceMetadataCollectionFactoryInterface $resourceMetadataCollectionFactory = null, protected ?ResourceAccessCheckerInterface $resourceAccessChecker = null, protected ?TagCollectorInterface $tagCollector = null)
     {
         if (!isset($defaultContext['circular_reference_handler'])) {
             $defaultContext['circular_reference_handler'] = fn ($object): ?string => $this->iriConverter->getIriFromResource($object);
@@ -164,16 +164,33 @@ public function normalize(mixed $object, string $format = null, array $context =
         $emptyResourceAsIri = $context['api_empty_resource_as_iri'] ?? false;
         unset($context['api_empty_resource_as_iri']);
 
-        if (isset($context['resources'])) {
+        if (!$this->tagCollector && isset($context['resources'])) {
             $context['resources'][$iri] = $iri;
         }
 
+        $context['object'] = $object;
+        $context['format'] = $format;
+
         $data = parent::normalize($object, $format, $context);
 
+        $context['data'] = $data;
+        unset($context['property_metadata']);
+        unset($context['api_attribute']);
+
         if ($emptyResourceAsIri && \is_array($data) && 0 === \count($data)) {
+            $context['data'] = $iri;
+
+            if ($this->tagCollector) {
+                $this->tagCollector->collect($context);
+            }
+
             return $iri;
         }
 
+        if ($this->tagCollector) {
+            $this->tagCollector->collect($context);
+        }
+
         return $data;
     }
 
@@ -633,7 +650,7 @@ protected function getFactoryOptions(array $context): array
     protected function getAttributeValue(object $object, string $attribute, string $format = null, array $context = []): mixed
     {
         $context['api_attribute'] = $attribute;
-        $propertyMetadata = $this->propertyMetadataFactory->create($context['resource_class'], $attribute, $this->getFactoryOptions($context));
+        $context['property_metadata'] = $propertyMetadata = $this->propertyMetadataFactory->create($context['resource_class'], $attribute, $this->getFactoryOptions($context));
 
         if ($context['api_denormalize'] ?? false) {
             return $this->propertyAccessor->getValue($object, $attribute);
@@ -670,7 +687,15 @@ protected function getAttributeValue(object $object, string $attribute, string $
 
                 $resourceClass = $this->resourceClassResolver->getResourceClass($attributeValue, $className);
 
-                return $this->normalizeCollectionOfRelations($propertyMetadata, $attributeValue, $resourceClass, $format, $childContext);
+                $data = $this->normalizeCollectionOfRelations($propertyMetadata, $attributeValue, $resourceClass, $format, $childContext);
+                $context['data'] = $data;
+                $context['type'] = $type;
+
+                if ($this->tagCollector) {
+                    $this->tagCollector->collect($context);
+                }
+
+                return $data;
             }
 
             if (
@@ -697,7 +722,15 @@ protected function getAttributeValue(object $object, string $attribute, string $
 
                 $resourceClass = $this->resourceClassResolver->getResourceClass($attributeValue, $className);
 
-                return $this->normalizeRelation($propertyMetadata, $attributeValue, $resourceClass, $format, $childContext);
+                $data = $this->normalizeRelation($propertyMetadata, $attributeValue, $resourceClass, $format, $childContext);
+                $context['data'] = $data;
+                $context['type'] = $type;
+
+                if ($this->tagCollector) {
+                    $this->tagCollector->collect($context);
+                }
+
+                return $data;
             }
 
             if (!$this->serializer instanceof NormalizerInterface) {
@@ -789,9 +822,15 @@ protected function normalizeRelation(ApiProperty $propertyMetadata, ?object $rel
             return $normalizedRelatedObject;
         }
 
-        $iri = $this->iriConverter->getIriFromResource(resource: $relatedObject, context: $context);
+        $context['iri'] = $iri = $this->iriConverter->getIriFromResource(resource: $relatedObject, context: $context);
+        $context['data'] = $iri;
+        $context['object'] = $relatedObject;
+        unset($context['property_metadata']);
+        unset($context['api_attribute']);
 
-        if (isset($context['resources'])) {
+        if ($this->tagCollector) {
+            $this->tagCollector->collect($context);
+        } elseif (isset($context['resources'])) {
             $context['resources'][$iri] = $iri;
         }
 

src/Serializer/ItemNormalizer.php

@@ -39,9 +39,9 @@ class ItemNormalizer extends AbstractItemNormalizer
 {
     private readonly LoggerInterface $logger;
 
-    public function __construct(PropertyNameCollectionFactoryInterface $propertyNameCollectionFactory, PropertyMetadataFactoryInterface $propertyMetadataFactory, IriConverterInterface $iriConverter, ResourceClassResolverInterface $resourceClassResolver, PropertyAccessorInterface $propertyAccessor = null, NameConverterInterface $nameConverter = null, ClassMetadataFactoryInterface $classMetadataFactory = null, LoggerInterface $logger = null, ResourceMetadataCollectionFactoryInterface $resourceMetadataFactory = null, ResourceAccessCheckerInterface $resourceAccessChecker = null, array $defaultContext = [])
+    public function __construct(PropertyNameCollectionFactoryInterface $propertyNameCollectionFactory, PropertyMetadataFactoryInterface $propertyMetadataFactory, IriConverterInterface $iriConverter, ResourceClassResolverInterface $resourceClassResolver, PropertyAccessorInterface $propertyAccessor = null, NameConverterInterface $nameConverter = null, ClassMetadataFactoryInterface $classMetadataFactory = null, LoggerInterface $logger = null, ResourceMetadataCollectionFactoryInterface $resourceMetadataFactory = null, ResourceAccessCheckerInterface $resourceAccessChecker = null, array $defaultContext = [], protected ?TagCollectorInterface $tagCollector = null)
     {
-        parent::__construct($propertyNameCollectionFactory, $propertyMetadataFactory, $iriConverter, $resourceClassResolver, $propertyAccessor, $nameConverter, $classMetadataFactory, $defaultContext, $resourceMetadataFactory, $resourceAccessChecker);
+        parent::__construct($propertyNameCollectionFactory, $propertyMetadataFactory, $iriConverter, $resourceClassResolver, $propertyAccessor, $nameConverter, $classMetadataFactory, $defaultContext, $resourceMetadataFactory, $resourceAccessChecker, $tagCollector);
 
         $this->logger = $logger ?: new NullLogger();
     }

src/Serializer/TagCollectorInterface.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\Serializer;
+
+/**
+ * Interface for collecting cache tags during normalization.
+ *
+ * @author Urban Suppiger <urban@suppiger.net>
+ */
+interface TagCollectorInterface
+{
+    /**
+     * Collect cache tags for cache invalidation.
+     *
+     * @param array<string, mixed>&array{iri?: string, data?: mixed, object?: mixed, property_metadata?: \ApiPlatform\Metadata\ApiProperty, api_attribute?: string, resources?: array<string, string>} $context
+     */
+    public function collect(array $context = []): void;
+}

src/Symfony/Bundle/Resources/config/api.xml

@@ -60,6 +60,8 @@
             <argument>null</argument>
             <argument type="service" id="api_platform.metadata.resource.metadata_collection_factory" on-invalid="ignore" />
             <argument type="service" id="api_platform.security.resource_access_checker" on-invalid="ignore" />
+            <argument type="collection" />
+            <argument type="service" id="api_platform.http_cache.tag_collector" on-invalid="ignore" />
 
             <!-- Run before serializer.normalizer.json_serializable -->
             <tag name="serializer.normalizer" priority="-895" />