feat(symfony): add enable_head_request_optimization config flag

Nayte91 · Nayte91 · commit 7726f2e6120d · 2026-06-24T23:35:24.000+02:00
HEAD responses now omit some observable headers (Content-Length, per-item cache tags); per semver that is a backward-
incompatible behavior change, so this commit ships an opt-out flag — set `enable_head_request_optimization: false` to restore the
prior GET-equivalent behavior.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,15 @@
 # Changelog
 
+HEAD requests no longer build the response body: the collection is never
+iterated (no row SELECT) and serialization is skipped. Two observable changes:
+
+- `Content-Length` is no longer set on HEAD (RFC 9110 §9.3.2 permits this).
+- Cache-tag/xkey headers are not emitted on HEAD. Previously HEAD carried the
+  same tags as GET, so cached HEAD responses were tag-purgeable; now they
+  invalidate by TTL only. Body-less, so impact is limited to stale headers.
+
+Restore the previous GET-equivalent behavior with `api_platform.enable_head_request_optimization: false`.
+
 ## v4.3.14
 
 ### Bug fixes
diff --git a/src/Hydra/State/JsonStreamerProcessor.php b/src/Hydra/State/JsonStreamerProcessor.php
@@ -59,6 +59,7 @@ public function __construct(
         private readonly string $enabledParameterName = 'pagination',
         private readonly int $urlGenerationStrategy = UrlGeneratorInterface::ABS_PATH,
         ?ResourceMetadataCollectionFactoryInterface $resourceMetadataCollectionFactory = null,
+        private readonly bool $enableHeadRequestOptimization = true,
     ) {
         $this->resourceClassResolver = $resourceClassResolver;
         $this->iriConverter = $iriConverter;
@@ -79,7 +80,7 @@ public function process(mixed $data, Operation $operation, array $uriVariables =
             return $this->processor?->process($data, $operation, $uriVariables, $context);
         }
 
-        if ($request->isMethod('HEAD')) {
+        if ($this->enableHeadRequestOptimization && $request->isMethod('HEAD')) {
             $response = new Response(
                 null,
                 $this->getStatus($request, $operation, $context),
diff --git a/src/Laravel/ApiPlatformProvider.php b/src/Laravel/ApiPlatformProvider.php
@@ -553,7 +553,7 @@ public function register(): void
         });
 
         $this->app->singleton(SerializeProcessor::class, static function (Application $app) {
-            return new SerializeProcessor($app->make(RespondProcessor::class), $app->make(Serializer::class), $app->make(SerializerContextBuilderInterface::class));
+            return new SerializeProcessor($app->make(RespondProcessor::class), $app->make(Serializer::class), $app->make(SerializerContextBuilderInterface::class), $app['config']->get('api-platform.enable_head_request_optimization', true));
         });
 
         $this->app->singleton(WriteProcessor::class, static function (Application $app) {
diff --git a/src/Laravel/config/api-platform.php b/src/Laravel/config/api-platform.php
@@ -49,6 +49,10 @@
     // on PATCH operations, allowing partial updates without requiring all fields.
     'partial_patch_validation' => false,
 
+    // When true (default), HEAD requests skip response body construction so
+    // collections are not iterated. Set to false to process HEAD like GET.
+    'enable_head_request_optimization' => true,
+
     'docs_formats' => [
         'jsonld' => ['application/ld+json'],
         // 'jsonapi' => ['application/vnd.api+json'],
diff --git a/src/Serializer/State/JsonStreamerProcessor.php b/src/Serializer/State/JsonStreamerProcessor.php
@@ -48,6 +48,7 @@ public function __construct(
         ?ResourceClassResolverInterface $resourceClassResolver = null,
         ?OperationMetadataFactoryInterface $operationMetadataFactory = null,
         ?ResourceMetadataCollectionFactoryInterface $resourceMetadataCollectionFactory = null,
+        private readonly bool $enableHeadRequestOptimization = true,
     ) {
         $this->resourceClassResolver = $resourceClassResolver;
         $this->iriConverter = $iriConverter;
@@ -68,7 +69,7 @@ public function process(mixed $data, Operation $operation, array $uriVariables =
             return $this->processor?->process($data, $operation, $uriVariables, $context);
         }
 
-        if ($request->isMethod('HEAD')) {
+        if ($this->enableHeadRequestOptimization && $request->isMethod('HEAD')) {
             $response = new Response(
                 null,
                 $this->getStatus($request, $operation, $context),
diff --git a/src/State/Processor/SerializeProcessor.php b/src/State/Processor/SerializeProcessor.php
@@ -46,6 +46,7 @@ public function __construct(
         private readonly ?ProcessorInterface $processor,
         private readonly SerializerInterface $serializer,
         private readonly SerializerContextBuilderInterface $serializerContextBuilder,
+        private readonly bool $enableHeadRequestOptimization = true,
     ) {
     }
 
@@ -60,7 +61,7 @@ public function process(mixed $data, Operation $operation, array $uriVariables =
         // @see ApiPlatform\State\Processor\RespondProcessor
         $context['original_data'] = $data;
 
-        if ($request->isMethod('HEAD')) {
+        if ($this->enableHeadRequestOptimization && $request->isMethod('HEAD')) {
             $this->stopwatch?->stop('api_platform.processor.serialize');
 
             return $this->processor?->process(null, $operation, $uriVariables, $context);
diff --git a/src/State/Tests/Processor/SerializeProcessorTest.php b/src/State/Tests/Processor/SerializeProcessorTest.php
@@ -41,4 +41,23 @@ public function testHeadRequestSkipsSerializationAndForwardsNull(): void
 
         $this->assertNull($processor->process(new \stdClass(), $operation, [], ['request' => $request]));
     }
+
+    public function testHeadRequestSerializesWhenOptimizationDisabled(): void
+    {
+        $request = Request::create('/foos', 'HEAD');
+
+        $serializer = $this->createMock(SerializerInterface::class);
+        $serializer->expects($this->once())->method('serialize')->willReturn('');
+
+        $inner = $this->createMock(ProcessorInterface::class);
+        $inner->method('process')->willReturn('forwarded');
+
+        $contextBuilder = $this->createStub(SerializerContextBuilderInterface::class);
+        $contextBuilder->method('createFromRequest')->willReturn([]);
+
+        $processor = new SerializeProcessor($inner, $serializer, $contextBuilder, false);
+        $operation = (new Get())->withSerialize(true);
+
+        $this->assertSame('forwarded', $processor->process(new \stdClass(), $operation, [], ['request' => $request]));
+    }
 }
diff --git a/src/Symfony/Bundle/DependencyInjection/ApiPlatformExtension.php b/src/Symfony/Bundle/DependencyInjection/ApiPlatformExtension.php
@@ -355,6 +355,7 @@ private function registerCommonConfiguration(ContainerBuilder $container, array
 
         $container->setParameter('api_platform.enable_entrypoint', $config['enable_entrypoint']);
         $container->setParameter('api_platform.enable_docs', $config['enable_docs']);
+        $container->setParameter('api_platform.enable_head_request_optimization', $config['enable_head_request_optimization']);
         $container->setParameter('api_platform.title', $config['title']);
         $container->setParameter('api_platform.description', $config['description']);
         $container->setParameter('api_platform.version', $config['version']);
diff --git a/src/Symfony/Bundle/DependencyInjection/Configuration.php b/src/Symfony/Bundle/DependencyInjection/Configuration.php
@@ -130,6 +130,7 @@ public function getConfigTreeBuilder(): TreeBuilder
                 ->booleanNode('enable_scalar')->defaultValue(class_exists(TwigBundle::class))->info('Enable Scalar API Reference')->end()
                 ->booleanNode('enable_entrypoint')->defaultTrue()->info('Enable the entrypoint')->end()
                 ->booleanNode('enable_docs')->defaultTrue()->info('Enable the docs')->end()
+                ->booleanNode('enable_head_request_optimization')->defaultTrue()->info('Skip response body construction on HEAD requests so collections are not iterated. Disable to process HEAD identically to GET.')->end()
                 ->booleanNode('enable_profiler')->defaultTrue()->info('Enable the data collector and the WebProfilerBundle integration.')->end()
                 ->booleanNode('enable_phpdoc_parser')->defaultTrue()->info('Enable resource metadata collector using PHPStan PhpDocParser.')->end()
                 ->booleanNode('enable_link_security')
diff --git a/src/Symfony/Bundle/Resources/config/json_streamer/events.php b/src/Symfony/Bundle/Resources/config/json_streamer/events.php
@@ -34,6 +34,7 @@
             '%api_platform.collection.pagination.enabled_parameter_name%',
             '%api_platform.url_generation_strategy%',
             service('api_platform.metadata.resource.metadata_collection_factory'),
+            '%api_platform.enable_head_request_optimization%',
         ]);
 
     $services->set('api_platform.jsonld.state_provider.json_streamer', HydraJsonStreamerProvider::class)
@@ -50,6 +51,7 @@
             service('api_platform.resource_class_resolver'),
             service('api_platform.metadata.operation.metadata_factory'),
             service('api_platform.metadata.resource.metadata_collection_factory'),
+            '%api_platform.enable_head_request_optimization%',
         ]);
 
     $services->set('api_platform.state_provider.json_streamer', JsonStreamerProvider::class)
diff --git a/src/Symfony/Bundle/Resources/config/json_streamer/hydra.php b/src/Symfony/Bundle/Resources/config/json_streamer/hydra.php
@@ -31,6 +31,7 @@
             '%api_platform.collection.pagination.enabled_parameter_name%',
             '%api_platform.url_generation_strategy%',
             service('api_platform.metadata.resource.metadata_collection_factory'),
+            '%api_platform.enable_head_request_optimization%',
         ]);
 
     $services->set('api_platform.jsonld.state_provider.json_streamer', JsonStreamerProvider::class)
diff --git a/src/Symfony/Bundle/Resources/config/json_streamer/json.php b/src/Symfony/Bundle/Resources/config/json_streamer/json.php
@@ -28,6 +28,7 @@
             service('api_platform.resource_class_resolver'),
             service('api_platform.metadata.operation.metadata_factory'),
             service('api_platform.metadata.resource.metadata_collection_factory'),
+            '%api_platform.enable_head_request_optimization%',
         ]);
 
     $services->set('api_platform.state_provider.json_streamer', JsonStreamerProvider::class)
diff --git a/src/Symfony/Bundle/Resources/config/state/processor.php b/src/Symfony/Bundle/Resources/config/state/processor.php
@@ -29,6 +29,7 @@
             service('api_platform.state_processor.serialize.inner'),
             service('api_platform.serializer'),
             service('api_platform.serializer.context_builder'),
+            '%api_platform.enable_head_request_optimization%',
         ]);
 
     $services->set('api_platform.state_processor.write', WriteProcessor::class)
diff --git a/src/Symfony/Bundle/Resources/config/symfony/events.php b/src/Symfony/Bundle/Resources/config/symfony/events.php
@@ -101,6 +101,7 @@
             null,
             service('api_platform.serializer'),
             service('api_platform.serializer.context_builder'),
+            '%api_platform.enable_head_request_optimization%',
         ]);
 
     $services->set('api_platform.state_processor.write', WriteProcessor::class)
@@ -162,6 +163,7 @@
             service('api_platform.state_processor.documentation.serialize.inner'),
             service('api_platform.serializer'),
             service('api_platform.serializer.context_builder'),
+            '%api_platform.enable_head_request_optimization%',
         ]);
 
     $services->set('api_platform.state_processor.documentation.write', WriteProcessor::class)
diff --git a/src/Symfony/Tests/Bundle/DependencyInjection/ApiPlatformExtensionTest.php b/src/Symfony/Tests/Bundle/DependencyInjection/ApiPlatformExtensionTest.php
@@ -261,6 +261,9 @@ public function testCommonConfiguration(): void
         foreach ($services as $service) {
             $this->assertNotContainerHasService($service);
         }
+
+        $this->assertTrue($this->container->hasParameter('api_platform.enable_head_request_optimization'));
+        $this->assertTrue($this->container->getParameter('api_platform.enable_head_request_optimization'));
     }
 
     public function testSwaggerUiDisabledConfiguration(): void
diff --git a/tests/Functional/HeadRequestWithoutOptimizationTest.php b/tests/Functional/HeadRequestWithoutOptimizationTest.php
@@ -0,0 +1,79 @@
+<?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\Tests\Functional;
+
+use ApiPlatform\Symfony\Bundle\Test\ApiTestCase;
+use ApiPlatform\Tests\Fixtures\TestBundle\ApiResource\HeadSpyResource;
+use ApiPlatform\Tests\SetupClassResourcesTrait;
+use Symfony\Component\Config\Loader\LoaderInterface;
+use Symfony\Component\DependencyInjection\ContainerBuilder;
+
+class HeadRequestWithoutOptimizationAppKernel extends \AppKernel
+{
+    public function getCacheDir(): string
+    {
+        return parent::getCacheDir().'/head_no_opt';
+    }
+
+    public function getLogDir(): string
+    {
+        return parent::getLogDir().'/head_no_opt';
+    }
+
+    protected function configureContainer(ContainerBuilder $c, LoaderInterface $loader): void
+    {
+        parent::configureContainer($c, $loader);
+
+        $loader->load(static function (ContainerBuilder $container): void {
+            $container->loadFromExtension('api_platform', [
+                'enable_head_request_optimization' => false,
+            ]);
+        });
+    }
+}
+
+/**
+ * Opt-out: with enable_head_request_optimization disabled, a HEAD request must
+ * behave like GET again — the body is built, so the (lazy) collection IS iterated.
+ * The spy paginator throws a fixed 418 on iteration; seeing it proves the flag
+ * restores the previous GET-equivalent behavior.
+ */
+final class HeadRequestWithoutOptimizationTest extends ApiTestCase
+{
+    use SetupClassResourcesTrait;
+
+    protected static ?bool $alwaysBootKernel = false;
+
+    /**
+     * @return class-string[]
+     */
+    public static function getResources(): array
+    {
+        return [HeadSpyResource::class];
+    }
+
+    protected static function getKernelClass(): string
+    {
+        return HeadRequestWithoutOptimizationAppKernel::class;
+    }
+
+    public function testHeadIteratesCollectionWhenOptimizationDisabled(): void
+    {
+        self::createClient()->request('HEAD', '/head_spy_resources', [
+            'headers' => ['Accept' => 'application/ld+json'],
+        ]);
+
+        $this->assertResponseStatusCodeSame(418);
+    }
+}
