README

PHP 库，用于表示 REST API 的 HAL 资源

PhpHal

PhpHal 是一个库，用于表示和消费不同格式的资源。

在 [HATEOAS API]（http://en.wikipedia.org/wiki/HATEOAS）中的资源必须描述其自身的功能和相互连接，这是 REST 成熟度模型的第三级。

为什么要使用超媒体？

如您在《设计超媒体 API》一书的序言中读到的

超媒体 API 承认使网络伟大的原则：灵活性、标准化和对任何给定服务的松散耦合。它们考虑了 Roy Fielding 在其论文中列举的系统设计原则（http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm），但使用较少的系统理论术语。

超媒体设计可扩展性更好，更容易更改，并促进解耦和封装，带来所有这些好处。缺点是它不一定是容错性最强的设计，如果不够小心，缓存可能会过时。它在单个请求级别上可能不如其他设计高效。

-- Steve Klabnik

我应该使用哪个超媒体规范？

超媒体目前正在被定义。只有最好的 API 才实现了超媒体。目前还没有事实上的标准，所以您必须在不同的规范之间进行选择。

PhpHal 目前实现或计划实现以下规范

• HAL：这是最常见和最活跃的。它有 JSON 和 XML 版本。
• Siren：目前正在定义。它实现了动作、类等一些有用的功能。
• Collection+JSON：这是一个面向 CRUD 的 API。

要求

• PHP 5.4.x

安装

安装 PhpHal 的推荐方法是 通过 composer。您可以在 Packagist 上查看软件包信息。

{
    "require": {
        "brandonlamb/php-hal": "dev-master"
    }
}

示例

Writer

基本资源，链接作为 application/hal+json

use PhpHal\Link;
use PhpHal\Resource;
use PhpHal\Format\Writer\Hal;

$resource = new Resource();
$resource->setURI('/foo');
$resource->setLink('foo', new Link('/bar'));
$resource->setData([
    'foo' => 'bar',
    'baz' => 'qux'
]);

$writer = new Hal\JsonWriter(true);
echo $writer->execute($resource);

{
    "foo": "bar",
    "baz": "qux",
    "_links": {
        "self": {
            "href": "/foo"
        },
        "foo": {
            "href": "/bar"
        }
    }
}

包含嵌入式资源的资源，作为 aapplication/vnd.siren+json

use PhpHal\Link;
use PhpHal\Resource;
use PhpHal\Format\Writer\Siren;

$resource = new Resource();
$resource->setRepositoryKey('index');
$resource->setURI('/index?page=2');
$resource->setLink('prev', new Link('/index?page=1'));
$resource->setLink('next', new Link('/index?page=3'));
$resource->addData('count', 5);

$subresource = [];
foreach (range(1, 5) as $value) {
    $subresource = new Resource();
    $subresource->addData('value', $value);

    $subresources[] = $subresource;
}

$resource->addResources('subresources', $subresources);

$writer = new Siren\JsonWriter(true);
echo $writer->execute($resource);

{
    "class": [
        "index"
    ],
    "properties": {
        "count": 5
    },
    "entities": [
        {
            "rel": "subresources",
            "class": [
                "index",
                "subresources"
            ],
            "properties": {
                "value": 1
            }
        },
        ...
        {
            "rel": "subresources",
            "class": [
                "index",
                "subresources"
            ],
            "properties": {
                "value": 5
            }
        }
    ],
    "links": [
        {
            "rel": "self",
            "href": "/index?page=2"
        },
        {
            "rel": "prev",
            "href": "/index?page=1"
        },
        {
            "rel": "next",
            "href": "/index?page=3"
        }
    ]
}

包含链接资源的资源，作为 application/hal+xml

use PhpHal\Link;
use PhpHal\Resource;
use PhpHal\Format\Writer\Hal;

$author = new Resource();
$author->setURI('/john-doe');
$author->setTitle('John Doe');

$article = new Resource();
$article->setURI('/lorem-ipsum');
$article->addData('description', 'Lorem ipsum dolor sit amet ...');
$article->linkResource('author', $author);

$writer = new Hal\XmlWriter(true);
echo $writer->execute($article);

<?xml version="1.0"?>
<resource href="/lorem-ipsum">
  <description>Lorem ipsum dolor sit amet ...</description>
  <link rel="author" href="/john-doe" title="John Doe"/>
</resource>

Reader

基本资源，链接作为 application/hal+json

use PhpHal\Format\Reader\Hal;

$json = '{"foo":"bar","baz":"qux","_links":{"self":{"href":"/foo"},"foo":{"href":"/bar"}}}';

$reader = new Hal\JsonReader();
$resource = $reader->execute($json);
print_r($resource);

PhpHal\Resource Object
(
    [uri:protected] => /foo
    [links:protected] => Array
        (
            [foo] => PhpHal\Link Object
                (
                    [href:protected] => /bar
                )

        )

    [data:protected] => Array
        (
            [foo] => bar
            [baz] => qux
        )

)

Tests

测试在 tests 文件夹中。要运行它们，您需要 PHPUnit。示例

$ phpunit --configuration phpunit.xml.dist

许可证

MIT，请参阅LICENSE