aeq / hal
Installs: 14 373
Dependents: 0
Suggesters: 0
Security: 0
Stars: 2
Watchers: 2
Forks: 0
Open Issues: 0
Requires
- php: >=5.5.0
- psr/http-message: ~1.0
- ql/uri-template: ^1.1
Requires (Dev)
- phpunit/phpunit: ^4.8
- squizlabs/php_codesniffer: ^2.5
Suggests
- guzzlehttp/guzzle: if your want to use the build in GuzzleClientAdapter
README
#PHP HAL (Hypertext Application Language) Explorer#
This library provides a full featured API to discover a HAL (Hypertext Application Language) API via an expressive interface.
$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
##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.
###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:
$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.
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.
$explorer->setClientAdapter(new MyCustomClientAdapter());
##Custom Serializers## Create a new class implementing the "SerializerInterface" and return the response.
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.
$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.
$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.
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.
$explorer->listenOnEvent(PostClientRequestEvent::class, new MyHandler());