告别硬编码与文档地狱：如何使用Composer和nocarrier/hal构建超媒体驱动的RESTfulAPI

<pre class="brush:php;toolbar:false;">{
    "orderId": "123",
    "total": 30.00,
    "currency": "USD",
    "customerId": "CUS1234"
}

<code class="bash">composer require nocarrier/hal</code>

<pre class="brush:php;toolbar:false;"><?php
require_once 'vendor/autoload.php';

use Nocarrier\Hal;

// 1. 创建一个订单列表的HAL资源
// 假设当前请求是 /orders
$ordersHal = new Hal('/orders');

// 2. 添加链接：让客户端知道如何获取下一页或搜索订单
$ordersHal->addLink('next', '/orders?page=2');
$ordersHal->addLink('search', '/orders?id={order_id}'); // 占位符表示可变参数

// 3. 创建一个具体的订单HAL资源
$order123 = new Hal(
    '/orders/123', // 订单的URI
    [
        'total' => 30.00,
        'currency' => 'USD',
        'status' => 'pending' // 订单数据
    ]
);

// 4. 为订单资源添加链接：引导客户端发现相关资源
$order123->addLink('customer', '/customers/CUS1234', ['title' => 'Bob Jones']);
$order123->addLink('items', '/orders/123/items');
$order123->addLink('cancel', '/orders/123/cancel', ['method' => 'POST']); // 甚至可以指示操作方法

// 5. 将订单资源嵌入到订单列表资源中
// 注意：addResource的第二个参数是一个Hal对象，它会被自动嵌入
$ordersHal->addResource('order', $order123);

// 6. 输出HAL+JSON格式的响应
header('Content-Type: application/hal+json');
echo $ordersHal->asJson(true); // true 参数用于美化输出
?>

<pre class="brush:php;toolbar:false;">{
    "_links": {
        "self": {
            "href": "/orders"
        },
        "next": {
            "href": "/orders?page=2"
        },
        "search": {
            "href": "/orders?id={order_id}"
        }
    },
    "_embedded": {
        "order": [
            {
                "total": 30,
                "currency": "USD",
                "status": "pending",
                "_links": {
                    "self": {
                        "href": "/orders/123"
                    },
                    "customer": {
                        "href": "/customers/CUS1234",
                        "title": "Bob Jones"
                    },
                    "items": {
                        "href": "/orders/123/items"
                    },
                    "cancel": {
                        "href": "/orders/123/cancel",
                        "method": "POST"
                    }
                }
            }
        ]
    }
}

<pre class="brush:php;toolbar:false;"><?php
use Nocarrier\Hal;

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

$hal = Hal::fromJson($jsonResponse);

// 遍历并打印所有链接
foreach ($hal->getLinks() as $rel => $links) {
    echo "关系: " . $rel . "\n";
    foreach ($links as $link) {
        echo "  URI: " . (string)$link . "\n";
    }
}

// 获取特定关系的链接
foreach ($hal->getLink('next') as $link) {
    echo "下一页链接: " . (string)$link . "\n";
}
?>