Link Laravel Package

Getting Started

Install the package with composer require psr/link. Remember: this is only interfaces, not a working implementation. To get going, also require a concrete provider like league/link or php-http/message (which includes PSR-13 support):

composer require psr/link league/link

Begin by type-hinting Link\EvolvableLinkInterface in services that generate or consume links—e.g., in API response transformers, Web Linking header builders, or HAL/JSON:API output formatters. Your first real use case will likely be generating Link headers for resources (RFC 5988), such as /users/1 with rel="self".

Implementation Patterns

• Factory-Based Link Generation: Inject a LinkFactory (e.g., from league/link) where links are needed. Use it to create fluent link instances:

  $link = $linkFactory->fromString('/posts/42')->withRel('canonical')->withAttribute('type', 'text/html');
  

• Middleware Integration: In Laravel, create middleware to append standardized links to responses (e.g., for pagination or resource relationships) using PSR-13 objects instead of raw strings:

  $next($request)->withHeader('Link', $prevLink->toString() . ', ' . $nextLink->toString());
  

• Transformer Delegation: Wrap PSR-13 links in Fractal or League transformer include methods to enrich HAL responses:

  $item->setLinks($links = [$prevLink, $nextLink]); // where $links are EvolvableLinkInterface[]
  

• Dependency Inversion: Accept EvolvableLinkInterface in constructors or methods to accept any compatible implementation—enabling easy swapping of link backends (e.g., for testing or future upgrades).

Gotchas and Tips

• No Runtime Behavior: This package alone cannot generate HTTP headers or parse links. Always pair it with an implementation—otherwise your code will compile but fail at runtime with missing concrete classes.
• Immutability Trap: with*() methods never mutate the original object. Forgetting to reassign:

  $link->withRel('prev'); // ❌ No effect
  $link = $link->withRel('prev'); // ✅ Required
  

• Attribute Type Flexibility: Since v2.0, withAttribute() accepts mixed (including arrays), but HTTP headers require string serialization. Test toString() output—e.g., arrays serialize as "; type=a:1:{i:0;s:3:"json"}" which may break clients. Cast non-scalar values to strings before setting.
• Interface Versioning: psr/link v2.x requires PHP 8.0+. If stuck on PHP 7.4, use v1.1.x, but note EvolvableLinkInterface::withAttribute() in v1 had stricter string|null typing—check compatibility with your chosen implementation.
• Testing Tip: Use phpspec or Laravel’s MockBuilder to mock EvolvableLinkInterface, ensuring your link-generation logic stays pure and isolated. Example:

  $mockLink = $this->mock(EvolvableLinkInterface::class);
  $mockLink->shouldReceive('toString')->andReturn('<https://api.example.com/users/1>; rel="self"');