README

RESTful APIs 的通信官

Uhura 是一个非常简单的 RESTful API 客户端，适用于几乎所有东西。无需设置模式或配置 API 端点，只需告诉 Uhura 你想要什么，然后去获取它。

$github = new Uhura('https://api.github.com');
$response = $github->users->colindecarlo->repos->get();

安装

使用 composer 安装 Uhura。

$ composer require uhura/uhura

发送请求

Uhura 将你在 Demeter 链中请求的内容映射到访问所需资源的 URL。

示例

向 http://someapi.com/users 发送 GET 请求

$uhura = new Uhura('http://someapi.com');
$response = $uhura->users->get();

向 http://someapi.com/users/1 发送 GET 请求

$uhura = new Uhura('http://someapi.com');
$response = $uhura->users(1)->get();

向 http://someapi.com/users/1/blogs/some-blog/comments 发送 GET 请求

$uhura = new Uhura('http://someapi.com');
$response = $uhura->users(1)->blogs('some-blog')->comments->get();

CRUD

使用 Uhura，CRUD 操作非常简单，分别映射到 create、get、update 和 delete 方法。

create(array $payload)

使用 Uhura 的 create 方法创建资源。该方法接受一个关联数组，作为 x-www-form-urlencoded 字符串发送到 API 的请求体中。

$uhura = new Uhura('http://someapi.com');
$uhura->users->create(['email' => 'example@example.com']);

get()

使用 Uhura 的 get 方法获取 API 资源。

$uhura = new Uhura('http://someapi.com');
$response = $uhura->users->get();

update($payload)

使用 Uhura 的 update 方法更新资源。该方法接受一个关联数组，作为 x-www-form-urlencoded 字符串发送到 API 的请求体中。

$uhura = new Uhura('http://someapi.com');
$uhura->users(1)->update(['name' => 'John Doe']);

delete()

使用 Uhura 的 delete 方法删除资源。

$uhura = new Uhura('http://someapi.com');
$uhura->users(1)->delete();

身份验证

Uhura 通过在每个请求中添加 Authorization 头来执行身份验证请求。

使用 HTTP Basic Auth

使用 useBasicAuthentication($username, $password) 方法告诉 Uhura 使用 HTTP Basic Auth。

$uhura = new Uhura('https://someapi.com');
$uhura->useBasicAuthentication('someuser', 'somepassword');

$uhura->user->update(['email' => 'example@example.com']);

显式设置身份验证头

您可以使用 Uhura 的 authenticate($token) 方法显式设置 Authorization 头的值。

$uhura = new Uhura('https://someapi.com');
$uhura->authenticate('Bearer somebearertoken');

$uhura->user->update(['email' => 'example@example.com']);

处理响应

默认情况下，Uhura 返回符合 PSR7 的响应对象。处理它们就像处理一个 GuzzleHttp\Psr7\Response 对象一样简单。

响应处理器

您可以告诉 Uhura 将 API 响应传递给响应处理器，以增强各种请求方法的返回值。例如，Uhura 随带一个 Json 响应处理器，它消费响应并返回解码后的 JSON 响应体。

$uhura = new Uhura('https://someapi.com');
$uhura->useResponseHandler(new Uhura\ResponseHandler\Json);

$uhura->users(1)->get();
/*
    [
        'email' => 'example@example.com',
        'name' => 'John Doe'
    ]
*/

编写自定义响应处理器

编写您自己的自定义响应处理器非常简单。响应处理器只是定义一个 handle($response) 方法的简单类。从 handle 方法返回的任何内容都是 Uhura 将返回给您的。

// XML Response Handler
class XmlHandler
{
    public function handle($response)
    {
        return new SimpleXMLElement($response->getBody()->getContents());
    }
}


$uhura = new Uhura('https://someapi.com');
$uhura->useResponseHandler(new XmlHandler);

echo (string)($uhura->users(1)->get());

/*
    <?xml version='1.0' standalone='yes'?>
    <user>
        <email>example@example.com</email>
        <name>John Doe</name>
    </user>
*/

作者

Colin DeCarlo, colin@thedecarlos.ca

许可证

Uhura 根据 MIT 许可证授权 - 有关详细信息，请参阅 LICENSE 文件。