Build a Hypermedia API response once in code and return it in multiple formats
NOTE: Currently in heavy active development, and some things may change, so be sure to version lock for stability.
Use the Composer basic usage guide, or use the following commands:
curl -s http://getcomposer.org/installer | php
php composer.phar require vlucas/hyperspan 0.x
php composer.phar install
There are two main components of Hyperspan: Hyperspan\Response
, which is used
to build an API response with specific attributes and types of data, and
Hyperspan\Formatter
, which is used to output the data in a sepcific
Hypermedia API response format.
The following code:
$res = new Hyperspan\Response();
$res->setProperties(array(
'foo' => 'bar',
'bar' => 'baz'
))
->addLink('self', 'http://localhost/foo/bar');
->addForm('add-item', array(
'method' => 'POST',
'href' => '/items',
'fields' => array(
'name' => array('type' => 'string'),
'body' => array('type' => 'text')
)
))
->addItem('item', array(
'some' => true,
'something' => 'else',
'three' => 3
));
$format = new Hyperspan\Formatter\Hal($res);
header('Content-Type', 'application/hal+json');
echo $format->toJson();
Will output the following JSON structure in HAL.
{
"foo": "bar",
"bar": "baz",
"_embedded": {
"item": {
"some": true,
"something": "else",
"three": 3
}
],
"_forms": [
"add-item": {
"method": "POST",
"href": "/items",
"fields": [
"name": { "type": "string" },
"body": { "type": "text" }
]
}
],
"_links": [
"self": { "href": "http://localhost/foo/bar" }
]
}
The following code:
$res = new Hyperspan\Response();
$res->title = 'Siren Sample JSON Response with Hyperspan';
$res->setProperties(array(
'foo' => 'bar',
'bar' => 'baz'
))
->addLink('self', 'http://localhost/foo/bar');
->addForm('add-item', array(
'title' => 'Add Item',
'method' => 'POST',
'href' => '/items',
'fields' => array(
array('name' => 'name', 'type' => 'string'),
array('name' => 'body', 'type' => 'text')
)
))
->addItem('item', array(
'some' => true,
'something' => 'else',
'three' => 3
));
$format = new Hyperspan\Formatter\Siren($res);
header('Content-Type', 'application/vnd.siren+json');
echo $format->toJson();
Will output the following JSON structure in Siren.
{
"title": "Siren Sample JSON Response with Hyperspan",
"properties": {
"foo": "bar",
"bar": "baz"
},
"entities": [
{
"properties": {
"some": true,
"something": "else",
"three": 3
}
}
],
"actions": [
{
"name": "add-item",
"title": "Add Item",
"method": "POST",
"href": "/items",
"fields": [
{ "name": "name", "type": "string" },
{ "name": "body", "type": "text" }
]
}
],
"links": [
{ "rel": [ "self" ], "href": "http://localhost/foo/bar" }
]
}