jsor/hal-client

A lightweight client for consuming and manipulating Hypertext Application Language (HAL) resources.

HalClient

A lightweight PHP client for consuming and manipulating Hypertext Application Language (HAL) resources., _(*1)

, _(*2)

• Installation
• Usage
• License

Installation

Install the latest version with Composer., _(*3)

composer require jsor/hal-client

Check the Packagist page for all available versions., _(*4)

HTTP Client dependency

The Hal client requires a HttpClientInterface implementation which can handle PSR-7 requests and responses., _(*5)

To use the default implementations shipped with this library, you need to install Guzzle 7, 6 or 5., _(*6)

composer require guzzlehttp/guzzle:"^5.0||^6.0||^7.0"

Usage

We will use Propilex as an example API endpoint., _(*7)

Create the client

At a first step, we setup a HalClient instance., _(*8)

use Jsor\HalClient\HalClient;

$client = new HalClient('http://propilex.herokuapp.com');

We can now set additional headers (eg. an Authorization header) which are sent with every request., _(*9)

$client = $client->withHeader('Authorization', 'Bearer 12345');

Note, that a client instance is immutable, which means, any call to change the state of the instance returns a new instance leaving the original instance unchanged., _(*10)

// Wrong!
$client->withHeader('Authorization', '...');
$resource = $client->get('/protected');

// Correct!
$client = $client->withHeader('Authorization', '...');
$resource = $client->get('/protected');

Browse the API

To start browsing through the API, we first get the root resource., _(*11)

/** @var \Jsor\HalClient\HalResource $rootResource */
$rootResource = $client->root();

We now follow the p:documents link., _(*12)

/** @var \Jsor\HalClient\HalLink $documentsLink */
$documentsLink = $rootResource->getFirstLink('documents');

$documentsResource = $documentsLink->get();

$totalDocuments = $documentsResource->getProperty('total');

foreach ($resource->getResource('documents') as $document) {
    echo $document->getProperty('title') . PHP_EOL;
}

If there is a second page with more documents, we can follow the next link., _(*13)

if ($documentsResource->hasLink('next')) {
    $nextDocumentsResource = $documentsResource->getFirstLink('next')->get();
}

Ok, let's create a new document., _(*14)

$newDocument = $documentsResource->post([
    'body' => [
        'title' => 'Sampl document',
        'body'  => 'Lorem ipsum'
    ]
]);

Oh noes! A typo in the document title. Let's fix it., _(*15)

$changedDocument = $newDocument->put([
    'body' => [
        'title' => 'Sampe document',
        'body'  => $newDocument->getProperty('body')
    ]
]);

Damn, we give up., _(*16)

$changedDocument->delete();

License

Copyright (c) 2015-2021 Jan Sorgalla. Released under the MIT License., _(*17)