ytake/hhhal

for HATEOAS REST web services

Hhypermedia

Hypertext Application Language for HHVM/Hack, _(*1)

, _(*2)

Supported

HAL - Hypertext Application Language
JSON Hypertext Application Language draft-kelly-json-hal-08
vnd.error, _(*3)

Requirements

HHVM 4.0.0 and above., _(*4)

1. Installation
2. Usage
3. vnd.error

1.Installation

$ composer require ytake/hhypermedia

2.Usage

Given a Hack Object, the hal+json transformer will represent the given data following the JSON Hypertext Application Language draft-kelly-json-hal-08 specification draft., _(*5)

Basic

use type Ytake\Hhypermedia\Serializer\HalJsonSerializer;
use type Ytake\Hhypermedia\Link;
use type Ytake\Hhypermedia\LinkResource;
use type Ytake\Hhypermedia\Serializer;
use type Ytake\Hhypermedia\HalResource;
use type Ytake\Hhypermedia\ResourceObject;
use type Ytake\Hhypermedia\Visitor\JsonSerializationVisitor;

$link = new Link('self', vec[new LinkResource('/users')]);
$ro = new ResourceObject()
|> $$->withLink($link);
$resource = new HalResource($ro, dict['id' => 123456789]);

$secondRo = new ResourceObject()
|> $$->withEmbedded('tests', vec[$resource]);
$hal = new HalResource($secondRo);
$s = new Serializer(
  new HalJsonSerializer(),
  $hal,
  new JsonSerializationVisitor()
);
echo $s->serialize();

Basic - Result

{
  "_embedded":{
    "tests":[
      {
        "id":123456789,
        "_links":{
          "self":{
            "href":"\/tests"
          }
        }
      }
    ]
  }
}

Curies

use type Ytake\Hhypermedia\Link;
use type Ytake\Hhypermedia\Curie;
use type Ytake\Hhypermedia\CurieResource;
use type Ytake\Hhypermedia\LinkResource;
use type Ytake\Hhypermedia\Serializer;
use type Ytake\Hhypermedia\HalResource;
use type Ytake\Hhypermedia\ResourceObject;
use type Ytake\Hhypermedia\Serializer\HalJsonSerializer;
use type Ytake\Hhypermedia\Visitor\JsonSerializationVisitor;

$ro = new ResourceObject()
|> $$->withLink(new Link('self', vec[new LinkResource('/tests')]))
|> $$->withLink(new Curie(vec[
  new CurieResource('http://haltalk.herokuapp.com/docs/{rel}', shape('name' => 'heroku'))
]));
$s = new Serializer(
  new HalJsonSerializer(),
  new HalResource($ro),
  new JsonSerializationVisitor()
);
echo $s->serialize();

Curies - Result

{
  "_links":{
    "self":{
      "href":"\/tests"
    },
    "curies":[
      {
        "href":"http:\/\/haltalk.herokuapp.com\/docs\/{rel}",
        "templated":true,
        "name":"heroku"
      }
    ]
  }
}

3.vnd.error

Supported the vnd.error., _(*6)

use type Ytake\Hhypermedia\Serializer;
use type Ytake\Hhypermedia\LinkResource;
use type Ytake\Hhypermedia\Error\ErrorLink;
use type Ytake\Hhypermedia\Error\MessageResource;
use type Ytake\Hhypermedia\ResourceObject;
use type Ytake\Hhypermedia\Serializer\VndErrorSerializer;
use type Ytake\Hhypermedia\Visitor\JsonSerializationVisitor;

$linkVec = vec[new LinkResource('http://...')];
$new = new ResourceObject()
|> $$->withLink( new ErrorLink('help', $linkVec))
|> $$->withLink( new ErrorLink('about', $linkVec))
|> $$->withLink( new ErrorLink('describes', $linkVec));

$s = new Serializer(
  new VndErrorSerializer(),
  new MessageResource(
    'Validation failed',
    $new,
    shape('logref' => 42, 'path' => '/username')
  ),
  new JsonSerializationVisitor()
);
\var_dump($s->toDict());

vnd.error - toDict

dict[
  'message' => 'Validation failed',
  'logref' => 42,
  'path' => '/username',
  '_links' => dict[
    'help' => dict[
      'href' => 'http://...'
    ],
    'about' => dict[
      'href' => 'http://...'
    ],
    'describes' => dict[
      'href' => 'http://...'
    ],
  ]
]

vnd.error - Result

{
  "message": "Validation failed",
  "path": "/username",
  "logref": 42,
  "_links": {
    "about": {
      "href": "http://..."
    },
    "describes": {
      "href": "http://..."
    },
    "help": {
      "href": "http://..."
    }
  }
}