README

这是一个用于创建 application/hal+json 和 application/hal+xml 超媒体格式的库

它需要 PHP 5.4 或更高版本。

<?php
require_once 'vendor/autoload.php';

use Nocarrier\Hal;

$hal = new Hal('/orders');
$hal->addLink('next', '/orders?page=2');
$hal->addLink('search', '/orders?id={order_id}');

$resource = new Hal(
    '/orders/123',
    array(
        'total' => 30.00,
        'currency' => 'USD',
    )
);

$resource->addLink('customer', '/customer/bob', array('title' => 'Bob Jones <bob@jones.com>'));
$hal->addResource('order', $resource);
echo $hal->asJson();
echo $hal->asXml();

安装

首选的安装方法是使用 packagist，因为这提供了 PSR-0 自动加载器功能。以下命令将下载并安装最新版本的 Hal 库到您的项目中。

php composer.phar require nocarrier/hal

或者，克隆项目并将其手动安装到您的项目中。

许可证

Nocarrier\Hal 在 MIT 许可证下授权。

用法

创建 Hal 资源

可以创建没有设置值的 Hal 资源

$hal = new \Nocarrier\Hal();

带有资源的 URI

$hal = new \Nocarrier\Hal('/orders');

以及一个数据数组

$hal = new \Nocarrier\Hal('/orders', ['customerId' => 'CUS1234']);

还可以从现有的 XML 或 JSON 文档创建 Hal 资源

$hal = \Nocarrier\Hal::fromJson($jsonString);

$hal = \Nocarrier\Hal::fromXml($xmlString);

$hal = \Nocarrier\Hal::fromXml($simpleXMLElement);

这两种方法的嵌套资源解析深度由第二个参数控制，默认为 0

$hal = \Nocarrier\Hal::fromJson($jsonString, 5);

获取表示

可以将 Hal 资源格式化为 JSON 或 XML

$hal = new \Nocarrier\Hal('/orders', ['customerId' => 'CUS1234']);
$hal->asJson();

其中第一个参数为 true 用于美化打印

$hal = new \Nocarrier\Hal('/orders', ['customerId' => 'CUS1234']);
$hal->asJson(true);

得到

{
    "customerId": "CUS1234",
    "_links": {
        "self": {"href": "/orders"}
    }
}

和

$hal = new \Nocarrier\Hal('/orders', ['customerId' => 'CUS1234']);
$hal->asXml(true);

得到

<?xml version="1.0"?>
<resource href="/orders">
    <customerId>CUS1234</customerId>
</resource>

数据

可以通过 setData 设置数据并通过 getData 读取

$hal = new \Nocarrier\Hal('/orders');
$hal->setData(['customerId' => 'CUS1234']);
$hal->getData();

在数据中使用数组键为 XML 表示添加前缀 @

$hal = new \Nocarrier\Hal('/orders');
$hal->setData(['customerId' => ['CUS1234', '@type' => 'legacy']]);

得到

<?xml version="1.0"?>
<resource href="/orders">
    <customerId value="CUS1234" type="legacy"/>
</resource>

如果渲染 JSON，@ 被忽略

{
    "customerId": {
        "value": "CUS1234",
        "type":" legacy"
    },
    "_links": {
        "self": {"href": "/orders"}
    }
}

链接

可以通过提供 rel 标识它们和 URI 来向资源中添加链接

$hal = new \Nocarrier\Hal('/orders', ['customerId' => 'CUS1234']);
$hal->addLink('next', '/orders?page=2');
$hal->addLink('search', '/orders?id={order_id}');

得到

{
    "customerId": "CUS1234",
    "_links": {
        "self": {
            "href": "/orders"
        },
        "next": {
            "href": "/orders?page=2"
        },
        "search": {
            "href": "/orders?id={order_id}"
        }
    }
}

如果从其他地方返回的响应中创建了 Hal 对象，则从其中检索链接可能会有所帮助。

$json = '{
     "customerId": "CUS1234",
     "_links": {
         "self": {
             "href": "/orders"
         },
         "next": {
             "href": "/orders?page=2"
         },
         "search": {
             "href": "/orders?id={order_id}"
         }
     }
 }';

$hal = \Nocarrier\Hal::fromJson($json);

foreach($hal->getLinks() as $rel => $links) {
    echo $rel."\n";
    foreach($links as $link) {
        echo (string) $link."\n";
    }
}

next
/orders?page=2
search
/orders?id={order_id}

和

$json = '{
     "customerId": "CUS1234",
     "_links": {
         "self": {
             "href": "/orders"
         },
         "next": {
             "href": "/orders?page=2"
         },
         "search": {
             "href": "/orders?id={order_id}"
         }
     }
 }';
$hal = \Nocarrier\Hal::fromJson($json);
foreach($hal->getLink('next') as $link) {
    echo (string) $link."\n";
}

输出

/orders?page=2

嵌套资源

除了链接到资源以便客户端可以获取它们外，还可以直接在资源中嵌入它们。

$hal = new \Nocarrier\Hal('/orders', ['customerId' => 'CUS1234']);

$resource = new \Nocarrier\Hal(
    '/orders/123',
    array(
        'total' => 30.00,
        'currency' => 'USD',
    )
);

$resource->addLink('customer', '/customer/bob', array('title' => 'Bob Jones <bob@jones.com>'));
$hal->addResource('order', $resource);

输出

{
    "customerId": "CUS1234",
    "_links": {
        "self": {
            "href": "/orders"
        }
    },
    "_embedded": {
        "order": [
            {
                "total": 30,
                "currency": "USD",
                "_links": {
                    "self": {
                        "href": "/orders/123"
                    },
                    "customer": {
                        "href": "/customer/bob",
                        "title": "Bob Jones <bob@jones.com>"
                    }
                }
            }
        ]
    }
}