jsor / hal-client
A lightweight client for consuming and manipulating Hypertext Application Language (HAL) resources.
Installs: 23 372
Dependents: 1
Suggesters: 0
Security: 0
Stars: 22
Watchers: 6
Forks: 11
Open Issues: 0
Requires
- php: ^7.2||^8.0
- ext-json: *
- guzzlehttp/psr7: ^1.0
- guzzlehttp/uri-template: ^1.0
- psr/http-message: ^1.0
Requires (Dev)
- friendsofphp/php-cs-fixer: ^3.1
- guzzlehttp/guzzle: ^5.0||^6.0||^7.0
- phpunit/phpunit: ^8.1
Suggests
- guzzlehttp/guzzle: For using Guzzle as your HTTP client
README
A lightweight PHP client for consuming and manipulating Hypertext Application Language (HAL) resources.
Installation
Install the latest version with Composer.
composer require jsor/hal-client
Check the Packagist page for all available versions.
HTTP Client dependency
The Hal client requires a HttpClientInterface implementation which can handle PSR-7 requests and responses.
To use the default implementations shipped with this library, you need to install Guzzle 7, 6 or 5.
composer require guzzlehttp/guzzle:"^5.0||^6.0||^7.0"
Usage
We will use Propilex as an example API endpoint.
Create the client
At a first step, we setup a HalClient
instance.
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.
$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.
// 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.
/** @var \Jsor\HalClient\HalResource $rootResource */ $rootResource = $client->root();
We now follow the p:documents
link.
/** @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.
if ($documentsResource->hasLink('next')) { $nextDocumentsResource = $documentsResource->getFirstLink('next')->get(); }
Ok, let's create a new document.
$newDocument = $documentsResource->post([ 'body' => [ 'title' => 'Sampl document', 'body' => 'Lorem ipsum' ] ]);
Oh noes! A typo in the document title. Let's fix it.
$changedDocument = $newDocument->put([ 'body' => [ 'title' => 'Sampe document', 'body' => $newDocument->getProperty('body') ] ]);
Damn, we give up.
$changedDocument->delete();
License
Copyright (c) 2015-2021 Jan Sorgalla. Released under the MIT License.