README

SimpleHal是一个易于使用的库，用于消费Hal API。

使用Composer进行安装

添加依赖项

composer require stormsys/simplehal

局限性

目前该库只支持GET请求，计划未来添加对PUT、POST和DELETE的支持。

使用方法

设置根资源

以下示例展示了如何设置根资源以开始导航。

<?php

use Guzzle\Http\Client;
use Stormsys\SimpleHal\Clients\GuzzleHalClient;
use Stormsys\SimpleHal\Resource;
use Stormsys\SimpleHal\Uri\GuzzleUriTemplateProcessor;
use Stormsys\SimpleHal\Uri\LeagueUriJoiner;

$client = new GuzzleHalClient(new Client());
$uriTemplateProcessor = new GuzzleUriTemplateProcessor();
$uriJoiner = new LeagueUriJoiner();
$apiRootUrl = 'http://haltalk.herokuapp.com';

$root = new Resource($client, $uriTemplateProcessor, $uriJoiner, $apiRootUrl);

跟随非模板链接

一旦你获得了资源，SimpleHal提供了几种方式来跟随链接。

$latestPosts = $root->follow('ht:latest-posts');

Simple hal提供了强大的PHP重载机制（见下方的魔法方法说明），使API更流畅，上述行也可以表示为以下形式

$latestPosts = $root->{'ht:latest-posts'};
$latestPosts = $root->{'ht:latest-posts'}();

跟随模板链接

类似于上述内容，你可以通过提供模板变量（如下所示）来跟随模板链接。

$john = $root->follow('ht:me', ['name' => 'john']);

再次使用重载（见下方的魔法方法说明）。

$john = $root->{'ht:me'}(['name' => 'john']);

读取嵌套资源

有时部分、不完整或完整的资源嵌入到Hal文档中，这些资源可以通过以下嵌套函数访问。

$postsArray = $latestPosts->embedded('ht:post');

对于嵌套资源，也提供了魔法访问器（见下方的魔法方法）。

$postsArray = $latestPosts->{'ht:post'};
$postsArray = $latestPosts->{'ht:post'}();

读取资源属性

要访问资源的属性，你可以使用以下所示的prop方法。

$johnsRealName = $john->prop('real_name');

就像以下关系和嵌套资源一样，属性也提供了魔法访问器（见下方的魔法方法）。以下是访问属性的所有等效方式。

以下是访问属性的所有等效方式。

$johnsRealName = $john->real_name;
$johnsRealName = $john->{'real_name'};
$johnsRealName = $john->{'real_name'}();
$johnsRealName = $john->real_name();

刷新/获取完整表示

你可以通过调用refresh()来更新或刷新已经加载的资源

$latestPosts = $latestPosts->refresh();

或者，如果你使用的是嵌套的局部资源，只要存在self链接，你可以使用这个，这只是一个对->refresh()的别名。

$firstPost = $postsArray[0]->full();

链式示例

以下示例展示了如何在Hal API上通过链式方法获取一些数据。

$postBody = $root->{'ht:latest-posts'}->{'ht:post'}[0]->content;
$postBody = $root->follow('ht:latest-posts')->{'ht:post'}[0]->content;
$postBody = $root->follow('ht:latest-posts')->embedded('ht:post')[0]->content;
$postBody = $root->follow('ht:latest-posts')->embedded('ht:post')[0]->prop('content');

魔法方法

你可以通过魔法访问器和方法重载访问嵌入的资源、跟随链接和访问属性。字段/方法的名称将与关系或属性名称相同。

SimpleHal将尝试解析请求的顺序是

• 通过链接关系嵌入资源
• 如果存在链接关系，则跟随链接以获取资源
• 返回资源的属性
• 如果上述所有都不存在，则返回null

理解请求解析的顺序很重要，因为库将选择找到的第一个，如果存在重复，则嵌入资源将被选择，而不是其他资源，在属性之前跟随链接。

接口

该库提供了以下接口，可以进行自定义实现。

• Stormsys\SimpleHal\Uri\UriTemplateProcessorInterface
• Stormsys\SimpleHal\Uri\UriJoinerInterface
• Stormsys\SimpleHal\Clients\HalClientInterface

默认情况下，库捆绑了以下实现

• Stormsys\SimpleHal\Uri\GuzzleUriTemplateProcessor
• Stormsys\SimpleHal\Uri\LeagueUriJoiner
• Stormsys\SimpleHal\Clients\GuzzleHalClient
• Stormsys\SimpleHal\Clients\FileGetContentsHalClient

TODO

• 添加测试
• 支持持久（POST/PUT）
• 支持删除