feat(state): RFC 8288 Link relations for paginated collections

src/Laravel/ApiPlatformProvider.php

@@ -169,6 +169,7 @@
 use ApiPlatform\State\Processor\AddLinkHeaderProcessor;
 use ApiPlatform\State\Processor\ObjectMapperInputProcessor;
 use ApiPlatform\State\Processor\ObjectMapperOutputProcessor;
+use ApiPlatform\State\Processor\PaginationLinkProcessor;
 use ApiPlatform\State\Processor\RespondProcessor;
 use ApiPlatform\State\Processor\SerializeProcessor;
 use ApiPlatform\State\Processor\WriteProcessor;
@@ -552,7 +553,7 @@ public function register(): void
                 );
             }
 
-            return new AddLinkHeaderProcessor($decorated, new HttpHeaderSerializer());
+            return new AddLinkHeaderProcessor(new PaginationLinkProcessor($decorated, $app->make(Pagination::class)), new HttpHeaderSerializer());
         });
 
         $this->app->singleton(SerializeProcessor::class, static function (Application $app) {

src/Metadata/ApiResource.php

@@ -982,6 +982,7 @@ public function __construct(
         protected array $extraProperties = [],
         ?bool $map = null,
         protected ?array $mcp = null,
+        protected ?bool $paginationLinkHeader = null,
     ) {
         parent::__construct(
             shortName: $shortName,
@@ -1273,6 +1274,19 @@ public function withAcceptPatch(string $acceptPatch): static
         return $self;
     }
 
+    public function getPaginationLinkHeader(): ?bool
+    {
+        return $this->paginationLinkHeader;
+    }
+
+    public function withPaginationLinkHeader(bool $paginationLinkHeader): static
+    {
+        $self = clone $this;
+        $self->paginationLinkHeader = $paginationLinkHeader;
+
+        return $self;
+    }
+
     public function getStatus(): ?int
     {
         return $this->status;

src/Metadata/Extractor/XmlResourceExtractor.php

@@ -124,6 +124,7 @@ private function buildBase(\SimpleXMLElement $resource): array
             'paginationClientItemsPerPage' => $this->phpize($resource, 'paginationClientItemsPerPage', 'bool'),
             'paginationClientPartial' => $this->phpize($resource, 'paginationClientPartial', 'bool'),
             'paginationEnabled' => $this->phpize($resource, 'paginationEnabled', 'bool'),
+            'paginationLinkHeader' => $this->phpize($resource, 'paginationLinkHeader', 'bool'),
             'paginationFetchJoinCollection' => $this->phpize($resource, 'paginationFetchJoinCollection', 'bool'),
             'paginationUseOutputWalkers' => $this->phpize($resource, 'paginationUseOutputWalkers', 'bool'),
             'paginationItemsPerPage' => $this->phpize($resource, 'paginationItemsPerPage', 'integer'),
@@ -429,6 +430,7 @@ private function buildOperations(\SimpleXMLElement $resource, array $root): ?arr
                 'queryParameterValidate' => $this->phpize($operation, 'queryParameterValidate', 'bool'),
                 'priority' => $this->phpize($operation, 'priority', 'integer'),
                 'routePriority' => $this->phpize($operation, 'routePriority', 'integer'),
+                'paginationLinkHeader' => $this->phpize($operation, 'paginationLinkHeader', 'bool'),
                 'name' => $this->phpize($operation, 'name', 'string'),
                 'routeName' => $this->phpize($operation, 'routeName', 'string'),
             ]);

src/Metadata/Extractor/YamlResourceExtractor.php

@@ -147,6 +147,7 @@ private function buildBase(array $resource): array
             'paginationClientItemsPerPage' => $this->phpize($resource, 'paginationClientItemsPerPage', 'bool'),
             'paginationClientPartial' => $this->phpize($resource, 'paginationClientPartial', 'bool'),
             'paginationEnabled' => $this->phpize($resource, 'paginationEnabled', 'bool'),
+            'paginationLinkHeader' => $this->phpize($resource, 'paginationLinkHeader', 'bool'),
             'paginationFetchJoinCollection' => $this->phpize($resource, 'paginationFetchJoinCollection', 'bool'),
             'paginationUseOutputWalkers' => $this->phpize($resource, 'paginationUseOutputWalkers', 'bool'),
             'paginationItemsPerPage' => $this->phpize($resource, 'paginationItemsPerPage', 'integer'),
@@ -366,6 +367,7 @@ private function buildOperations(array $resource, array $root): ?array
                 'hideHydraOperation' => $this->phpize($resource, 'hideHydraOperation', 'bool'),
                 'priority' => $this->phpize($operation, 'priority', 'integer'),
                 'routePriority' => $this->phpize($operation, 'routePriority', 'integer'),
+                'paginationLinkHeader' => $this->phpize($operation, 'paginationLinkHeader', 'bool'),
                 'name' => $this->phpize($operation, 'name', 'string'),
                 'class' => (string) $class,
             ]);

src/Metadata/Extractor/schema/resources.xsd

@@ -540,6 +540,7 @@
         <xsd:attribute type="xsd:boolean" name="stateless"/>
         <xsd:attribute type="xsd:string" name="sunset"/>
         <xsd:attribute type="xsd:string" name="acceptPatch"/>
+        <xsd:attribute type="xsd:boolean" name="paginationLinkHeader"/>
         <xsd:attribute type="xsd:positiveInteger" name="status"/>
         <xsd:attribute type="xsd:string" name="host"/>
         <xsd:attribute type="xsd:string" name="condition"/>

src/Metadata/GetCollection.php

@@ -107,6 +107,7 @@ public function __construct(
         ?bool $throwOnNotFound = null,
         private ?string $itemUriTemplate = null,
         ?bool $map = null,
+        ?bool $paginationLinkHeader = null,
     ) {
         parent::__construct(
             uriTemplate: $uriTemplate,
@@ -192,7 +193,8 @@ class: $class,
             strictQueryParameterValidation: $strictQueryParameterValidation,
             hideHydraOperation: $hideHydraOperation,
             stateOptions: $stateOptions,
-            map: $map
+            map: $map,
+            paginationLinkHeader: $paginationLinkHeader
         );
     }
 

src/Metadata/HttpOperation.php

@@ -227,6 +227,7 @@ public function __construct(
         ?bool $throwOnNotFound = null,
         array $extraProperties = [],
         ?bool $map = null,
+        protected ?bool $paginationLinkHeader = null,
     ) {
         $this->formats = (null === $formats || \is_array($formats)) ? $formats : [$formats];
         $this->inputFormats = (null === $inputFormats || \is_array($inputFormats)) ? $inputFormats : [$inputFormats];
@@ -518,6 +519,19 @@ public function withAcceptPatch(string $acceptPatch): static
         return $self;
     }
 
+    public function getPaginationLinkHeader(): ?bool
+    {
+        return $this->paginationLinkHeader;
+    }
+
+    public function withPaginationLinkHeader(bool $paginationLinkHeader): static
+    {
+        $self = clone $this;
+        $self->paginationLinkHeader = $paginationLinkHeader;
+
+        return $self;
+    }
+
     public function getStatus(): ?int
     {
         return $this->status;

src/Metadata/Tests/Extractor/Adapter/XmlResourceAdapter.php

@@ -46,6 +46,7 @@ final class XmlResourceAdapter implements ResourceAdapterInterface
         'paginationClientItemsPerPage',
         'paginationClientPartial',
         'paginationEnabled',
+        'paginationLinkHeader',
         'paginationFetchJoinCollection',
         'paginationUseOutputWalkers',
         'paginationItemsPerPage',

src/Metadata/Tests/Extractor/Adapter/resources.yaml

@@ -90,6 +90,7 @@ resources:
                     paginationViaCursor:
                         userId: DESC
                     paginationEnabled: false
+                    paginationLinkHeader: false
                     paginationFetchJoinCollection: false
                     paginationUseOutputWalkers: false
                     paginationItemsPerPage: 54
@@ -350,3 +351,4 @@ resources:
                     'Lorem ipsum': 'Dolor sit amet'
             map: null
             mcp: null
+            paginationLinkHeader: true

src/Metadata/Tests/Extractor/ResourceMetadataCompatibilityTest.php

@@ -84,6 +84,7 @@ final class ResourceMetadataCompatibilityTest extends TestCase
             'paginationClientItemsPerPage' => true,
             'paginationClientPartial' => true,
             'paginationEnabled' => true,
+            'paginationLinkHeader' => true,
             'paginationFetchJoinCollection' => true,
             'paginationUseOutputWalkers' => true,
             'paginationItemsPerPage' => 42,
@@ -389,6 +390,7 @@ final class ResourceMetadataCompatibilityTest extends TestCase
                         'userId' => 'DESC',
                     ],
                     'paginationEnabled' => false,
+                    'paginationLinkHeader' => false,
                     'paginationFetchJoinCollection' => false,
                     'paginationUseOutputWalkers' => false,
                     'paginationItemsPerPage' => 54,
@@ -513,6 +515,7 @@ final class ResourceMetadataCompatibilityTest extends TestCase
         'jsonldContext',
         'openapi',
         'paginationViaCursor',
+        'paginationLinkHeader',
         'stateOptions',
         'links',
         'rules',

src/Metadata/Tests/Extractor/XmlExtractorTest.php

@@ -56,6 +56,7 @@ public function testValidXML(): void
                     'paginationClientItemsPerPage' => null,
                     'paginationClientPartial' => null,
                     'paginationEnabled' => null,
+                    'paginationLinkHeader' => null,
                     'paginationFetchJoinCollection' => null,
                     'paginationUseOutputWalkers' => null,
                     'paginationItemsPerPage' => null,
@@ -132,6 +133,7 @@ public function testValidXML(): void
                     'paginationClientItemsPerPage' => null,
                     'paginationClientPartial' => null,
                     'paginationEnabled' => null,
+                    'paginationLinkHeader' => null,
                     'paginationFetchJoinCollection' => null,
                     'paginationUseOutputWalkers' => null,
                     'paginationItemsPerPage' => null,
@@ -280,6 +282,7 @@ public function testValidXML(): void
                             'method' => null,
                             'priority' => null,
                             'routePriority' => null,
+                            'paginationLinkHeader' => null,
                             'processor' => null,
                             'provider' => null,
                             'itemUriTemplate' => null,
@@ -390,6 +393,7 @@ public function testValidXML(): void
                             'method' => null,
                             'priority' => null,
                             'routePriority' => null,
+                            'paginationLinkHeader' => null,
                             'processor' => null,
                             'provider' => null,
                             'stateOptions' => null,

src/Metadata/Tests/Extractor/YamlExtractorTest.php

@@ -55,6 +55,7 @@ public function testValidYaml(): void
                     'paginationClientItemsPerPage' => null,
                     'paginationClientPartial' => null,
                     'paginationEnabled' => null,
+                    'paginationLinkHeader' => null,
                     'paginationFetchJoinCollection' => null,
                     'paginationUseOutputWalkers' => null,
                     'paginationItemsPerPage' => null,
@@ -131,6 +132,7 @@ public function testValidYaml(): void
                     'paginationClientItemsPerPage' => null,
                     'paginationClientPartial' => null,
                     'paginationEnabled' => null,
+                    'paginationLinkHeader' => null,
                     'paginationFetchJoinCollection' => null,
                     'paginationUseOutputWalkers' => null,
                     'paginationItemsPerPage' => null,
@@ -205,6 +207,7 @@ public function testValidYaml(): void
                     'paginationClientItemsPerPage' => null,
                     'paginationClientPartial' => null,
                     'paginationEnabled' => null,
+                    'paginationLinkHeader' => null,
                     'paginationFetchJoinCollection' => null,
                     'paginationUseOutputWalkers' => null,
                     'paginationItemsPerPage' => null,
@@ -321,6 +324,7 @@ public function testValidYaml(): void
                             'queryParameterValidate' => null,
                             'priority' => null,
                             'routePriority' => null,
+                            'paginationLinkHeader' => null,
                             'processor' => null,
                             'provider' => null,
                             'itemUriTemplate' => null,
@@ -413,6 +417,7 @@ public function testValidYaml(): void
                             'queryParameterValidate' => null,
                             'priority' => null,
                             'routePriority' => null,
+                            'paginationLinkHeader' => null,
                             'processor' => null,
                             'provider' => null,
                             'stateOptions' => null,
@@ -462,6 +467,7 @@ public function testValidYaml(): void
                     'paginationClientItemsPerPage' => null,
                     'paginationClientPartial' => null,
                     'paginationEnabled' => null,
+                    'paginationLinkHeader' => null,
                     'paginationFetchJoinCollection' => null,
                     'paginationUseOutputWalkers' => null,
                     'paginationItemsPerPage' => null,

src/State/Processor/PaginationLinkProcessor.php

@@ -0,0 +1,108 @@
+<?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\State\Processor;
+
+use ApiPlatform\Metadata\CollectionOperationInterface;
+use ApiPlatform\Metadata\HttpOperation;
+use ApiPlatform\Metadata\Operation;
+use ApiPlatform\Metadata\UrlGeneratorInterface;
+use ApiPlatform\Metadata\Util\IriHelper;
+use ApiPlatform\State\Pagination\Pagination;
+use ApiPlatform\State\Pagination\PaginatorInterface;
+use ApiPlatform\State\Pagination\PartialPaginatorInterface;
+use ApiPlatform\State\ProcessorInterface;
+use ApiPlatform\State\Util\CorsTrait;
+use Symfony\Component\HttpFoundation\Request;
+use Symfony\Component\WebLink\GenericLinkProvider;
+use Symfony\Component\WebLink\Link;
+
+/**
+ * A single-page collection still gets `first` and `last`, where the body links emit nothing: a HEAD response
+ * (RFC 9110 §9.3.2) carries no body from which a client could derive them. Cursor pagination is out of
+ * scope: RFC 8288 relations address pages, not cursors.
+ *
+ * @template T1
+ * @template T2
+ *
+ * @implements ProcessorInterface<T1, T2>
+ *
+ * @author Julien Robic <nayte91@gmail.com>
+ */
+final class PaginationLinkProcessor implements ProcessorInterface
+{
+    use CorsTrait;
+
+    /**
+     * @param ProcessorInterface<T1, T2> $decorated
+     */
+    public function __construct(private readonly ProcessorInterface $decorated, private readonly Pagination $pagination)
+    {
+    }
+
+    public function process(mixed $data, Operation $operation, array $uriVariables = [], array $context = []): mixed
+    {
+        if (
+            !($request = $context['request'] ?? null)
+            || !$request instanceof Request
+            || !$operation instanceof HttpOperation
+            || !$operation instanceof CollectionOperationInterface
+            || true !== $operation->getPaginationLinkHeader()
+            || null !== $operation->getPaginationViaCursor()
+            || $this->isPreflightRequest($request)
+        ) {
+            return $this->decorated->process($data, $operation, $uriVariables, $context);
+        }
+
+        $paginator = $context['original_data'] ?? $data;
+        if (!$paginator instanceof PartialPaginatorInterface) {
+            return $this->decorated->process($data, $operation, $uriVariables, $context);
+        }
+
+        $options = $this->pagination->getOptions();
+        $pageParameterName = $options['page_parameter_name'];
+        $parsed = IriHelper::parseIri($request->getUri(), $pageParameterName);
+        $parameters = $parsed['parameters'];
+
+        $itemsPerPage = $paginator->getItemsPerPage();
+
+        $urlGenerationStrategy = $operation->getUrlGenerationStrategy() ?? UrlGeneratorInterface::ABS_PATH;
+        $url = static fn (float $page): string => IriHelper::createIri($parsed['parts'], $parameters, $pageParameterName, $page, $urlGenerationStrategy);
+
+        // REFACTOR-WHEN: a third consumer of the page-link math appears → move Hydra's PaginationHelperTrait to State\Util and share it
+        $currentPage = $paginator->getCurrentPage();
+        $lastPage = $paginator instanceof PaginatorInterface ? $paginator->getLastPage() : null;
+
+        $pages = ['self' => $currentPage];
+        if (null !== $lastPage) {
+            $pages['first'] = 1.;
+        }
+        if ($currentPage > 1.) {
+            $pages['prev'] = $currentPage - 1.;
+        }
+        if ((null !== $lastPage && $currentPage < $lastPage) || (null === $lastPage && \count($paginator) >= $itemsPerPage)) {
+            $pages['next'] = $currentPage + 1.;
+        }
+        if (null !== $lastPage) {
+            $pages['last'] = $lastPage;
+        }
+
+        $linkProvider = $request->attributes->get('_api_platform_links') ?? new GenericLinkProvider();
+        foreach ($pages as $rel => $page) {
+            $linkProvider = $linkProvider->withLink(new Link($rel, $url($page)));
+        }
+        $request->attributes->set('_api_platform_links', $linkProvider);
+
+        return $this->decorated->process($data, $operation, $uriVariables, $context);
+    }
+}

src/Symfony/Bundle/DependencyInjection/ApiPlatformExtension.php

@@ -360,6 +360,7 @@ private function registerCommonConfiguration(ContainerBuilder $container, array
             $loader->load('state/processor.php');
         }
         $loader->load('state/parameter_provider.php');
+        $loader->load('state/pagination_link.php');
 
         $container->setParameter('api_platform.enable_entrypoint', $config['enable_entrypoint']);
         $container->setParameter('api_platform.enable_docs', $config['enable_docs']);