aeq/hal

PHP HAL (Hypertext Application Language) Explorer

, _(*1)

This library provides a full featured API to discover a HAL (Hypertext Application Language) API via an expressive interface., _(*2)

$posts = $resource->getLink('posts')->follow();

Features * GuzzleHttp as default HTTP Client * integrate custom HTTP clients easily * human readable API * Shipped with a simple default serializer for JSON responses * Possibility to integrate custom serializers * Fully tested * Used in production projects, _(*3)

Usage

1. Initiate the Explorer

$explorer = new Explorer();
$explorer->setClientAdapter(new GuzzleClientAdapter(new Client()));
$explorer->setSerializer(new JsonSerializer());

If you want to use the the build in "GuzzleClientAdapter" you have to require guzzlehttp/guzzle manually in your composer project since guzzle is only suggested., _(*4)

2. Request your API

$response = $explorer->request('GET', '/my/api/');

3. Explore the response

$resource = $explorer->explore($response);

4. Discover your API

$posts = $resource->getLink('posts')->follow();
foreach($posts as $post) {
    $publisher = $post->getLink('publisher')->follow();
    $company = $publisher->getLink('company')->follow();
}

The result of following a link is that the resolved resource is appended to the parent „$resource“ object („_embedded“). This allows you to access the linked resource without resolving the link again:, _(*5)

$posts = $resource->getEmbedded('posts');
foreach($posts as $post) {
    $publisher = $post->getEmbedded('publisher');
    $company = $publisher->getEmbedded('company');
}

Custom HTTP Clients

Create a new class implementing the "ClientAdapterInterface" and return the response as PSR-7., _(*6)

use Aeq\Hal\Client\ClientAdapterInterface;

class MyCustomClientAdapter implements ClientAdapterInterface
{
    public function request($method, $uri = null, array $options = [])
    {
        // call your custom client and return the response
    }
}

Set the custom client adapter to your explorer before using it., _(*7)

$explorer->setClientAdapter(new MyCustomClientAdapter());

Custom Serializers

Create a new class implementing the "SerializerInterface" and return the response., _(*8)

use Aeq\Hal\Serializer\SerializerInterface;

class MyCustomSerializer implements SerializerInterface
{
    public function serialize($data)
    {
        // serialize your data: $data
    }

    public function deserialize($str)
    {
        // deserialize the string: $str
    }
}

Set the custom serializer to your explorer before using it., _(*9)

$explorer->setSerializer(new MyCustomSerializer());

Events

This library offers you some events to listen on. To use the event system you have to add the "EventManager" to your Explorer before using it., _(*10)

$explorer->setEventManager(new EventManager());

To listen on a specific event you have to implement a Listener. A Listener is a PHP object with a public method "handle". As parameter your will get the triggered Event object., _(*11)

class MyHandler
{
    public function handle(EventInterface $event)
    {
        // process your stuff
    }
}

PostClientRequestEvent

This event is called on each executed request (after following a link or using the "request" method) and contains the complete PSR-7 response., _(*12)

$explorer->listenOnEvent(PostClientRequestEvent::class, new MyHandler());