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']);

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

$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>"
                    }
                }
            }
        ]
    }
}