Add PSR-13 Link implementation by dereuromark · Pull Request #19213 · cakephp/cakephp

dereuromark · 2026-01-22T08:19:27Z

Summary

Adds PSR-13 LinkInterface and LinkProviderInterface implementations for hypermedia link support.

Cake\Http\Link\Link implements EvolvableLinkInterface
Cake\Http\Link\LinkProvider implements EvolvableLinkProviderInterface
Full test coverage

Usage

use Cake\Http\Link\Link;
use Cake\Http\Link\LinkProvider;

// Create links
$self = new Link('/api/users/1', 'self');
$next = new Link('/api/users?page=2', 'next');

// With attributes
$link = (new Link('/api/users'))
    ->withRel('collection')
    ->withAttribute('type', 'application/json');

// Collect links
$provider = new LinkProvider([$self, $next]);
foreach ($provider->getLinksByRel('self') as $link) {
    echo $link->getHref();
}

Changes

Added psr/link to composer.json requirements
Added psr/link-implementation to composer.json provides
New classes in src/Http/Link/
Tests in tests/TestCase/Http/Link/

Refs: PSR-13 https://www.php-fig.org/psr/psr-13/

Adds Link and LinkProvider classes implementing PSR-13 EvolvableLinkInterface and EvolvableLinkProviderInterface. - Link: represents a hypermedia link (RFC 5988/8288) - LinkProvider: collects and provides links - Full test coverage

array<string>|string instead of string|array<string>

src/Http/Link/Link.php

src/Http/Link/LinkProvider.php

tests/TestCase/Http/Link/LinkProviderTest.php

tests/TestCase/Http/Link/LinkTest.php

composer.json

dereuromark · 2026-01-22T19:05:01Z

So far this itself is not useful yet.
We would need to decide how this could be properly used, otherwise we would need to abandon support for PSR-13.

@SInCE

- Update @SInCE from 5.2.0 to 5.4.0 in Link classes and tests - Add psr/link dependency to src/Http/composer.json - Add psr/link-implementation to provides - Add PSR-13 to description and keywords

LordSimal · 2026-01-22T20:09:47Z

~~maybe there is a place in HTML or Form Helper for this~~

I am stupid, this is about HTTP Header Links, not HTML links 🤦🏻

dereuromark · 2026-01-23T17:12:51Z

Integration Points

Just some ideas:

1. Response Integration

Add methods to ServerRequest or Response to manage links:

// In Response or via a trait
public function withLink(LinkInterface $link): static
public function getLinks(): LinkProviderInterface

2. LinkHeaderMiddleware

Automatically converts links to HTTP Link: headers:

// Response with links gets header:
// Link: </css/app.css>; rel="preload"; as="style"

3. View Helper

For outputting <link> tags in HTML:

// In template
echo $this->Html->linkTag($this->response->getLinks());

4. Pagination Integration

Auto-add rel="next", rel="prev", rel="first", rel="last" links from PaginatorHelper.

Implementation Options

Option	Description
LinkHeaderMiddleware	Reads links from response attributes, outputs `Link:` headers
Response trait/methods	`withLink()`, `withLinks()`, `getLinks()` on Response
PaginatorHelper integration	Auto-generate pagination links as PSR-13 objects

markstory · 2026-01-24T22:49:33Z

I think for us to provide PSR-13 support we'd need to also include some of the integration points that @dereuromark outlined. Without those I don't see the point.

- Add withLink(), withoutLink(), getLinks(), withLinkProvider() to Response - Add LinkHeaderMiddleware to convert PSR-13 links to HTTP Link headers - Add tests for Response link methods and LinkHeaderMiddleware

src/Http/Response.php

src/Http/Link/Link.php

src/Http/Middleware/LinkHeaderMiddleware.php

… array_values()

Per review feedback, Link headers are now emitted by ResponseEmitter (similar to cookie handling) instead of requiring a separate middleware. Removed LinkHeaderMiddleware and added tests to ResponseEmitterTest.

src/Http/ResponseEmitter.php

LordSimal

I wouldn't have needed this till now but maybe someone will eventually.

dereuromark added 3 commits January 22, 2026 09:19

Add PSR-13 Link implementation.

8da553e

Adds Link and LinkProvider classes implementing PSR-13 EvolvableLinkInterface and EvolvableLinkProviderInterface. - Link: represents a hypermedia link (RFC 5988/8288) - LinkProvider: collects and provides links - Full test coverage

Fix coding standards issues.

274c940

Fix PHPDoc type hint order.

eb75a57

array<string>|string instead of string|array<string>

dereuromark added the RFC label Jan 22, 2026

dereuromark added this to the 5.4.0 milestone Jan 22, 2026