MKHal

This repository is still in a early development stage. If you find any issues or miss any feature please feel free to raise an issue.

MKHal is an implementation of the HAL specification written in PHP. It can be used to build a HAL specific data structure and convert it to JSON or XML. It can be easily implemented in your current API backend workflow.

Requirements

• PHP 7.0 or higher

Installation

You can clone or download the package and use it in your project or just install it via composer:

composer require mk/hal

Usage

Object types

MKHal offers different class types to represent the structure of a typical HAL implementation:

• HALObject: The HALObject class represents the main resource in the HAL specification. It can hold normal data, HALLink objects and HALCurie objects. It can also embed additional HALObjects in referred by labels.
• HALLink: The HALLink class represents a typical link resources in the _links section of the HAL document. It can hold different information like the href attribute. It get automatically serialized along with an HALObject instance. A HALObject can hold additional links after different labels.
• HALCurie: The HALCurie class is the representation of the curies attribute in HAL. An HALObject instance can have multiple curies inside of it.

Basic usage

use MK\HAL\HALObject;
use MK\HAL\HALLink;
use MK\HAL\HALCurie;

$hal = new HALObject('/orders');

$hal->addData(array(
    "offers" => 5,
    "prices" => array(
        "normal" => "10.99",
        "season" => "5.99"
    )
));

$hal->addCurie(new HALCurie('ea', 'http://example.com/docs/rels/{rel}'));

$hal->addLink('next', new HALLink('/orders?page=2'));

$hal->addLinkCollection('ea:admin', array(
    new HALLink('/admin/2'),
    new HALLink('/admin/5')
));

$product = new HALObject('/product/1');
$product->addLink('next', new HALLink('/product/2'));

$hal->embed('product', $product);

$hal->embedCollection('coupon', array(
    new HALObject('/coupon/5'),
    new HALObject('/coupon/6')
));

// use export() for json serialization
echo $hal->export(); // calls json_encode internally
// or simple encode the HALObject
echo json_encode($hal);

The call of the export() method creates a JSON representation of the HAL specification:

{
    "_links": {
        "self": {
            "href": "/orders"
        },
        "curies": [
            {
                "name": "ea",
                "href": "http://example.com/docs/rels/{rel}",
                "templated": true
            }
        ],
        "next": {
            "href": "/orders?page=2"
        },
        "ea:admin": [
            {
                "href": "/admin/2"
            },
            {
                "href": "/admin/5"
            }
        ]
    },
    "offers": 5,
    "prices": {
        "normal": "10.99",
        "season": "5.99"
    },
    "_embedded": {
        "product": {
            "_links": {
                "self": {
                    "href": "/product/1"
                },
                "next": {
                    "href": "/product/2"
                }
            }
        },
        "coupon": [
            {
                "_links": {
                    "self": {
                        "href": "/coupon/5"
                    }
                }
            },
            {
                "_links": {
                    "self": {
                        "href": "/coupon/6"
                    }
                }
            }
        ]
    }
}

Roadmap

• Implement basic HAL specification
• Enable curies
• Well structured class hierarchy
• JSON export / output
• Auto create HAL data from given objects
• XML export / output
• Read HAL objects to use library as client too
• Slim Framework integration