README

Level3 Resource 是一个用于表示和消费不同 超媒体 格式的库。

在 [HATEOAS API] (http://en.wikipedia.org/wiki/HATEOAS) 中的资源必须描述其自身的能力和相互关系，这是 REST 成熟度模型的第三层。

为什么需要超媒体？

正如您可以在 Designing Hypermedia APIs 一书的序言中所读到的

超媒体 API 接受了使网络变得伟大的原则：灵活性、标准化以及与任何特定服务的松散耦合。它们考虑了 Roy Fielding 在他的论文中列举的系统设计原则 （http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm），但稍微减少了一些系统理论的术语。

超媒体设计具有更好的可扩展性，更容易更改，并促进了解耦和封装，所有这些都带来了好处。然而，它可能不是最具延迟容忍度的设计，如果您不小心，缓存可能会过时。它在单个请求级别上可能不如其他设计高效。

-- Steve Klabnik

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

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

Level3 Resource 目前实现或计划实现以下规范

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

要求

• PHP 5.4.x
• hampel/json >= 1.0

安装

推荐通过 composer 安装 Level3 Resource。您可以在 Packagist 上查看 包信息。

{
    "require": {
        "level3/resource": "dev-master"
    }
}

示例

写入器

以链接形式为application/hal+json的基本资源

use Level3\Resource\Link;
use Level3\Resource\Resource;
use Level3\Resource\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 Level3\Resource\Link;
use Level3\Resource\Resource;
use Level3\Resource\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 Level3\Resource\Link;
use Level3\Resource\Resource;
use Level3\Resource\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>

读取器

以链接形式为application/hal+json的基本资源

use Level3\Resource\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);

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

        )

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

)

测试

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

$ phpunit --configuration phpunit.xml.dist

许可证

MIT，见LICENSE