Build a Hypermedia API response once and return it in multiple formats
PHP
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
src/Hyperspan
tests
.gitignore
.travis.yml
LICENSE.txt
README.md
composer.json
phpunit.xml

README.md

Hyperspan

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.

Installation

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

Overview

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.

Supported Hypermedia Formats

HAL JSON Usage

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" }
  ]
}

Siren JSON Usage

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" }
  ]
}