graviton/link-header-rel-parser

A small library that parses and generates RESTful Link headers with rel attributes (relations)

v1.0.1 2022-10-14 06:52 UTC

This package is auto-updated.

Last update: 2024-03-14 09:57:21 UTC


README

Build Status Latest Stable Version Total Downloads License

This is a small standalone PHP library that helps with parsing and creating Link header contents with rel="" attributes as it is used in the context of RESTful web services.

It is a tolerant parser, silently accepting invalid input. You can use the API functions to check if a given rel exists.

Installation

The preferred way to install library is through composer.

Either run

composer require graviton/link-header-rel-parser

or add

"graviton/link-header-rel-parser": "*",

to the require section of your composer.json.

Examples

Parsing headers

Parsing an existing header is easy, just pass the plain header contents to the static function:

$header = '<http://localhost/service/self>; rel="self", '<http://localhost/service/next>; rel="next"';
$linkHeader = LinkHeader::fromString($header);

$selfUrl = $linkHeader->getRel('self')->getUri(); // will output 'http://localhost/service/self'

If you are using Symfony, just fetch the Link header from the Request or Response object and pass it to the library.

Creating headers

You can create header contents programmatically:

$header = new LinkHeader();
$header->add(new LinkHeaderItem('http://localhost?limit(10,10)', 'self'));
$header->add(new LinkHeaderItem('http://localhost?limit(10,30)', 'next'));
$header->add(new LinkHeaderItem('http://localhost?limit(10,0)', 'prev'));

echo (string) $header;

Will produce

<http://localhost?limit(10,10)>; rel="self", <http://localhost?limit(10,30)>; rel="next", <http://localhost?limit(10,0)>; rel="prev"

Manipulating existing

Combining both methods above, you can also parse existing headers, manipulate them and render them.

$header = '<http://localhost/service/self>; rel="self", '<http://localhost/service/next>; rel="next"';
$linkHeader = LinkHeader::fromString($header);

$linkHeader->add(new LinkHeaderItem('http://localhost?limit(10,10)', 'prev'));
$linkHeader->removeRel('next');
$header->getRel('self')->setUri('http://newhost');

echo (string) $header;

Will produce

<http://newhost>; rel="self", <http://localhost?limit(10,10)>; rel="prev"