Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/jsor/hal-client
A lightweight client for consuming and manipulating Hypertext Application Language (HAL) resources.
https://github.com/jsor/hal-client
api client hal http hypertext-application-language php
Last synced: about 2 months ago
JSON representation
A lightweight client for consuming and manipulating Hypertext Application Language (HAL) resources.
- Host: GitHub
- URL: https://github.com/jsor/hal-client
- Owner: jsor
- License: mit
- Created: 2015-10-09T12:19:01.000Z (about 9 years ago)
- Default Branch: main
- Last Pushed: 2021-12-23T09:37:45.000Z (almost 3 years ago)
- Last Synced: 2024-10-14T17:18:12.152Z (2 months ago)
- Topics: api, client, hal, http, hypertext-application-language, php
- Language: PHP
- Homepage:
- Size: 115 KB
- Stars: 22
- Watchers: 6
- Forks: 11
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
HalClient
=========
A lightweight PHP client for consuming and manipulating
[Hypertext Application Language (HAL)](https://tools.ietf.org/html/draft-kelly-json-hal)
resources.
[](https://github.com/jsor/hal-client/actions/workflows/ci.yml)
[](https://coveralls.io/github/jsor/hal-client?branch=main)
* [Installation](#installation)
* [Usage](#usage)
* [License](#license)
Installation
------------
Install the latest version with [Composer](http://getcomposer.org).
```bash
composer require jsor/hal-client
```
Check the [Packagist page](https://packagist.org/packages/jsor/hal-client) for
all available versions.
### HTTP Client dependency
The Hal client requires a [HttpClientInterface](src/HttpClient/HttpClientInterface.php)
implementation which can handle [PSR-7](http://www.php-fig.org/psr/psr-7/)
requests and responses.
To use the default implementations shipped with this library, you need to
install Guzzle 7, 6 or 5.
```bash
composer require guzzlehttp/guzzle:"^5.0||^6.0||^7.0"
```
Usage
-----
We will use [Propilex](http://propilex.herokuapp.com) as an example API
endpoint.
### Create the client
At a first step, we setup a `HalClient` instance.
```php
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.
```php
$client = $client->withHeader('Authorization', 'Bearer 12345');
```
Note, that a client instance is [immutable](https://en.wikipedia.org/wiki/Immutable_object),
which means, any call to change the state of the instance returns a **new**
instance leaving the original instance unchanged.
```php
// 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.
```php
/** @var \Jsor\HalClient\HalResource $rootResource */
$rootResource = $client->root();
```
We now follow the `p:documents` link.
```php
/** @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.
```php
if ($documentsResource->hasLink('next')) {
$nextDocumentsResource = $documentsResource->getFirstLink('next')->get();
}
```
Ok, let's create a new document.
```php
$newDocument = $documentsResource->post([
'body' => [
'title' => 'Sampl document',
'body' => 'Lorem ipsum'
]
]);
```
Oh noes! A typo in the document title. Let's fix it.
```php
$changedDocument = $newDocument->put([
'body' => [
'title' => 'Sampe document',
'body' => $newDocument->getProperty('body')
]
]);
```
Damn, we give up.
```php
$changedDocument->delete();
```
License
-------
Copyright (c) 2015-2021 Jan Sorgalla.
Released under the [MIT License](LICENSE).