Ability to modify response headers (mainly cache related headers) (#2288)

* Allow user-defined cache headers

A user may wish to define response cache headers in a custom controller or per resource. E.g. a /entity/random endpoint should have a max-age of 0

* Override cache max-age and shared-max-age

Add annotation attributes for cache_headers which allows max_age and shared_max_age to be assigned per resource.

* Remove unused property

The property was added when I thought it may be good to have the option outside of 'attributes' - decided to put the option in attributes instead and failed to remove this property.

* Code style fixes

* Test code style fix

* Review changes applied

- Order of constructor arguments + default null value
- Remove 'throws' annotation
- setting $resourceCacheHeaders with default fallback to empty array
- Improved conditional statements

* Add cacheHeaders Attribute annotation

* Accidental typo

* Alphabetical order

Updated attribute annotation to alphabetical order - moved the property into alphabetical order as well

Author: silverbackdan

src/Annotation/ApiResource.php

@@ -26,6 +26,7 @@
  *     @Attribute("accessControl", type="string"),
  *     @Attribute("accessControlMessage", type="string"),
  *     @Attribute("attributes", type="array"),
+ *     @Attribute("cacheHeaders", type="array"),
  *     @Attribute("collectionOperations", type="array"),
  *     @Attribute("denormalizationContext", type="array"),
  *     @Attribute("deprecationReason", type="string"),
@@ -109,6 +110,13 @@ final class ApiResource
      */
     private $accessControlMessage;
 
+    /**
+     * @see https://github.com/Haehnchen/idea-php-annotation-plugin/issues/112
+     *
+     * @var array
+     */
+    private $cacheHeaders;
+
     /**
      * @see https://github.com/Haehnchen/idea-php-annotation-plugin/issues/112
      *

src/Bridge/Symfony/Bundle/Resources/config/http_cache.xml

@@ -11,6 +11,7 @@
             <argument>%api_platform.http_cache.shared_max_age%</argument>
             <argument>%api_platform.http_cache.vary%</argument>
             <argument>%api_platform.http_cache.public%</argument>
+            <argument type="service" id="api_platform.metadata.resource.metadata_factory" />
 
             <tag name="kernel.event_listener" event="kernel.response" method="onKernelResponse" priority="-1" />
         </service>

src/HttpCache/EventListener/AddHeadersListener.php

@@ -13,6 +13,7 @@
 
 namespace ApiPlatform\Core\HttpCache\EventListener;
 
+use ApiPlatform\Core\Metadata\Resource\Factory\ResourceMetadataFactoryInterface;
 use ApiPlatform\Core\Util\RequestAttributesExtractor;
 use Symfony\Component\HttpKernel\Event\FilterResponseEvent;
 
@@ -30,14 +31,16 @@ final class AddHeadersListener
     private $sharedMaxAge;
     private $vary;
     private $public;
+    private $resourceMetadataFactory;
 
-    public function __construct(bool $etag = false, int $maxAge = null, int $sharedMaxAge = null, array $vary = null, bool $public = null)
+    public function __construct(bool $etag = false, int $maxAge = null, int $sharedMaxAge = null, array $vary = null, bool $public = null, ResourceMetadataFactoryInterface $resourceMetadataFactory = null)
     {
         $this->etag = $etag;
         $this->maxAge = $maxAge;
         $this->sharedMaxAge = $sharedMaxAge;
         $this->vary = $vary;
         $this->public = $public;
+        $this->resourceMetadataFactory = $resourceMetadataFactory;
     }
 
     public function onKernelResponse(FilterResponseEvent $event)
@@ -53,23 +56,29 @@ public function onKernelResponse(FilterResponseEvent $event)
             return;
         }
 
-        if ($this->etag) {
+        $resourceCacheHeaders = [];
+        if ($this->resourceMetadataFactory && $attributes = RequestAttributesExtractor::extractAttributes($request)) {
+            $resourceMetadata = $this->resourceMetadataFactory->create($attributes['resource_class']);
+            $resourceCacheHeaders = $resourceMetadata->getOperationAttribute($attributes, 'cache_headers', [], true);
+        }
+
+        if ($this->etag && !$response->getEtag()) {
             $response->setEtag(md5($response->getContent()));
         }
 
-        if (null !== $this->maxAge) {
-            $response->setMaxAge($this->maxAge);
+        if (null !== ($maxAge = $resourceCacheHeaders['max_age'] ?? $this->maxAge) && !$response->headers->hasCacheControlDirective('max-age')) {
+            $response->setMaxAge($maxAge);
         }
 
         if (null !== $this->vary) {
             $response->setVary(array_diff($this->vary, $response->getVary()), false);
         }
 
-        if (null !== $this->sharedMaxAge) {
-            $response->setSharedMaxAge($this->sharedMaxAge);
+        if (null !== ($sharedMaxAge = $resourceCacheHeaders['shared_max_age'] ?? $this->sharedMaxAge) && !$response->headers->hasCacheControlDirective('s-maxage')) {
+            $response->setSharedMaxAge($sharedMaxAge);
         }
 
-        if (null !== $this->public) {
+        if (null !== $this->public && !$response->headers->hasCacheControlDirective('public')) {
             $this->public ? $response->setPublic() : $response->setPrivate();
         }
     }

tests/Annotation/ApiResourceTest.php

@@ -29,7 +29,7 @@ public function testConstruct()
         $resource = new ApiResource([
             'accessControl' => 'has_role("ROLE_FOO")',
             'accessControlMessage' => 'You are not foo.',
-            'attributes' => ['foo' => 'bar', 'validation_groups' => ['baz', 'qux']],
+            'attributes' => ['foo' => 'bar', 'validation_groups' => ['baz', 'qux'], 'cache_headers' => ['max_age' => 0, 'shared_max_age' => 0]],
             'collectionOperations' => ['bar' => ['foo']],
             'denormalizationContext' => ['groups' => ['foo']],
             'description' => 'description',
@@ -85,6 +85,7 @@ public function testConstruct()
             'pagination_partial' => true,
             'route_prefix' => '/foo',
             'validation_groups' => ['baz', 'qux'],
+            'cache_headers' => ['max_age' => 0, 'shared_max_age' => 0],
             'sunset' => 'Thu, 11 Oct 2018 00:00:00 +0200',
         ], $resource->attributes);
     }
@@ -107,6 +108,7 @@ public function testApiResourceAnnotation()
             'route_prefix' => '/whatever',
             'access_control' => "has_role('ROLE_FOO')",
             'access_control_message' => 'You are not foo.',
+            'cache_headers' => ['max_age' => 0, 'shared_max_age' => 0],
         ], $resource->attributes);
     }
 

tests/Fixtures/AnnotatedClass.php

@@ -23,7 +23,7 @@
  *     itemOperations={"foo"={"bar"}},
  *     collectionOperations={"bar"={"foo"}},
  *     graphql={"query"={"normalization_context"={"groups"={"foo", "bar"}}}},
- *     attributes={"foo"="bar", "route_prefix"="/whatever"},
+ *     attributes={"foo"="bar", "route_prefix"="/whatever", "cache_headers"={"max_age"=0, "shared_max_age"=0}},
  *     routePrefix="/foo",
  *     accessControl="has_role('ROLE_FOO')",
  *     accessControlMessage="You are not foo."

tests/HttpCache/EventListener/AddHeadersListenerTest.php

@@ -14,6 +14,8 @@
 namespace ApiPlatform\Core\Tests\HttpCache\EventListener;
 
 use ApiPlatform\Core\HttpCache\EventListener\AddHeadersListener;
+use ApiPlatform\Core\Metadata\Resource\Factory\ResourceMetadataFactoryInterface;
+use ApiPlatform\Core\Metadata\Resource\ResourceMetadata;
 use ApiPlatform\Core\Tests\Fixtures\TestBundle\Entity\Dummy;
 use PHPUnit\Framework\TestCase;
 use Symfony\Component\HttpFoundation\Request;
@@ -81,11 +83,56 @@ public function testAddHeaders()
         $event->getRequest()->willReturn($request)->shouldBeCalled();
         $event->getResponse()->willReturn($response)->shouldBeCalled();
 
-        $listener = new AddHeadersListener(true, 100, 200, ['Accept', 'Accept-Encoding'], true);
+        $factory = $this->prophesize(ResourceMetadataFactoryInterface::class);
+        $factory->create(Dummy::class)->willReturn(new ResourceMetadata())->shouldBeCalled();
+
+        $listener = new AddHeadersListener(true, 100, 200, ['Accept', 'Accept-Encoding'], true, $factory->reveal());
         $listener->onKernelResponse($event->reveal());
 
         $this->assertSame('"9893532233caff98cd083a116b013c0b"', $response->getEtag());
         $this->assertSame('max-age=100, public, s-maxage=200', $response->headers->get('Cache-Control'));
         $this->assertSame(['Accept', 'Cookie', 'Accept-Encoding'], $response->getVary());
     }
+
+    public function testDoNotSetHeaderWhenAlreadySet()
+    {
+        $request = new Request([], [], ['_api_resource_class' => Dummy::class, '_api_item_operation_name' => 'get']);
+        $response = new Response('some content', 200, ['Vary' => ['Accept', 'Cookie']]);
+        $response->setEtag('etag');
+        $response->setMaxAge(300);
+        // This also calls setPublic
+        $response->setSharedMaxAge(400);
+
+        $event = $this->prophesize(FilterResponseEvent::class);
+        $event->getRequest()->willReturn($request)->shouldBeCalled();
+        $event->getResponse()->willReturn($response)->shouldBeCalled();
+
+        $factory = $this->prophesize(ResourceMetadataFactoryInterface::class);
+        $factory->create(Dummy::class)->willReturn(new ResourceMetadata())->shouldBeCalled();
+
+        $listener = new AddHeadersListener(true, 100, 200, [], true, $factory->reveal());
+        $listener->onKernelResponse($event->reveal());
+
+        $this->assertSame('"etag"', $response->getEtag());
+        $this->assertSame('max-age=300, public, s-maxage=400', $response->headers->get('Cache-Control'));
+    }
+
+    public function testSetHeadersFromResourceMetadata()
+    {
+        $request = new Request([], [], ['_api_resource_class' => Dummy::class, '_api_item_operation_name' => 'get']);
+        $response = new Response('some content', 200, ['Vary' => ['Accept', 'Cookie']]);
+
+        $event = $this->prophesize(FilterResponseEvent::class);
+        $event->getRequest()->willReturn($request)->shouldBeCalled();
+        $event->getResponse()->willReturn($response)->shouldBeCalled();
+
+        $metadata = new ResourceMetadata(null, null, null, null, null, ['cache_headers' => ['max_age' => 123, 'shared_max_age' => 456]]);
+        $factory = $this->prophesize(ResourceMetadataFactoryInterface::class);
+        $factory->create(Dummy::class)->willReturn($metadata)->shouldBeCalled();
+
+        $listener = new AddHeadersListener(true, 100, 200, ['Accept', 'Accept-Encoding'], true, $factory->reveal());
+        $listener->onKernelResponse($event->reveal());
+
+        $this->assertSame('max-age=123, public, s-maxage=456', $response->headers->get('Cache-Control'));
+    }
 }