README

废弃

此组件已被废弃且不再维护。我们建议使用 Guzzle（它具有 中间件功能，可启用 API 访问），以及/或基于 Guzzle 的工具（例如，Uhura），这些工具提供通用的 API 访问功能。

zendservice-api 是一个用于在 PHP 中消耗通用 API 调用的微 HTTP 框架。此框架可用于创建使用简单配置数组（或文件）消耗特定 HTTP API 的 PHP 库。

此项目使用了 Zend Framework 的 zend-http 组件。

安装

您可以使用以下命令使用 composer 安装此组件：

composer require zendframework/zendservice-api

用法

可以使用 ZendService\Api 组件通过 HTTP 促进对通用 API 的消耗。此库能够根据特定的 API 参数配置 HTTP 请求的头、方法、主体和查询字符串。

此映射是通过特殊 PHP 配置数组提供的。

您可以使用 setApi 方法指定 API 参数。此方法接受两个参数：API 的名称和一个返回包含 PHP 数组的配置的闭包（回调）。

让我们看看一个例子，假设您需要使用 POST HTTP 请求和一个 JSON 数据格式（具有以下参数：username 和 password）消耗一个身份验证 API 调用。

HTTP 请求可以表示如下：

POST /v1/auth HTTP/1.1
Host: localhost
Connection: close
Content-Type: application/json
Content-Length: 57

{ 'auth' : { 'username' : 'admin', 'password' : 'test' }}

您需要使用以下方式使用 setApi 方法配置 API 调用（我们使用 auth 名称为此 API）

use ZendService\Api\Api;

$api = new Api();
$api->setApi('auth', function ($params) {
    return array(
        'url' => 'http://localhost/v1/auth',
        'header' => array(
            'Content-Type' => 'application/json'
        ),
        'method' => 'POST',
        'body' => json_encode(array(
            'auth' => array(
                'username' => $params[0],
                'password' => $params[1]
            )
        )),
        'response' => array(
            'valid_codes' => array('200')
        )
    );
});

之后，您可以使用 auth 函数执行 API 调用（此函数由 PHP 的魔法 __call 函数管理）

$result = $api->auth('username', 'password');
if ($api->isSuccess()) {
    var_dump($result);
} else {
    printf("Error (%d): %s\n", $api->getStatusCode(), $api->getErrorMsg());
}

使用数组 $params 管理与 auth 参数和 API 规范的映射。您必须使用 $params 的数值索引来匹配函数中参数的顺序。使用配置数组，您可以指定 API 请求的所有 HTTP 数据（头、主体、URI 等）。您还可以在 response 部分的 valid_codes 参数中指定成功请求的 HTTP 状态码。

使用配置文件

您还可以使用配置文件进行 API 调用，而不是使用 setApi 方法。您需要创建一个与 API 调用同名的 PHP 文件。此文件包含 API 配置数组。例如，对于前面的示例，您必须创建一个包含以下数组的 auth.php 文件

return array(
    'url' => 'http://localhost/v1/auth',
    'header' => array(
        'Content-Type' => 'application/json'
    ),
    'method' => 'POST',
    'body' => json_encode(array(
        'auth' => array(
            'username' => $params[0],
            'password' => $params[1]
        )
    )),
    'response' => array(
        'valid_codes' => array('200')
    )
);

您需要使用以下方式设置包含此配置文件的目录

use ZendService\Api\Api;

$api = new Api();
$api->setApiPath('path/to/api/config');
$result = $api->auth('username', 'password');
if ($api->isSuccess()) {
    var_dump($result);
} else {
    printf("Error (%d): %s\n", $api->getStatusCode(), $api->getErrorMsg());
}

设置API调用的基础URL

如果您需要从同一个基础URL调用不同的API，可以使用setUri函数。此函数设置基础URL，您可以使用相对URI进行特定的API调用，例如，假设您需要使用URLhttp://identity.api.openstack.org来消费OpenStack服务，我们可以将此地址设置为基础URL，并使用相对地址进行每个API调用。

use ZendService\Api\Api;

$api = new Api();
$api->setUrl('http://identity.api.openstack.org');
$api->setApi('authentication', function ($params) {
    return array(
        'url' => '/v2.0/tokens',
        'header' => array(
            'Content-Type' => 'application/json'
        ),
        'method' => 'POST',
        'body' => json_encode(array(
            'auth' => array(
                'passwordCredentials' => array(
                    'username' => $params[0],
                    'password' => $params[1]
                )
            )
        )),
        'response' => array(
            'valid_codes' => array('200', '203')
        )
    );
});
$result = $api->authentication('username', 'password');
if ($api->isSuccess()) {
    printf("Authenticate!\n");
} else {
    printf("Error (%d): %s\n", $api->getStatusCode(), $api->getErrorMsg());
}

注意在API配置中uri参数中使用相对地址。

API调用中的查询字符串

如果您需要在API HTTP调用中传递查询字符串，可以使用Api类的setQueryParams方法。例如，假设您需要在前面示例中传递HTTP查询字符串?auth=strong，您可以使用以下代码

use ZendService\Api\Api;

$api = new Api();
$api->setQueryParams(array( 'auth' => 'strong' ));
$result = $api->authenticate('username', 'password');
if ($api->isSuccess()) {
    printf("OK!\n");
} else {
    printf("Error (%d): %s\n", $api->getStatusCode(), $api->getErrorMsg());
}

您可以通过不带参数调用setQueryParams()函数来重置查询字符串。

设置默认HTTP头

您可以为所有HTTP调用指定默认HTTP头。例如，如果您需要通过特殊头字段传递身份验证令牌来调用供应商API，可以使用此功能为所有后续API调用设置默认头。

要设置默认头，可以使用setHeaders函数，下面是一个示例

use ZendService\Api\Api;

$api = new Api();
$api->setApiPath('path/to/api/config');
$api->setHeaders(array( 'X-Auth-Token' => 'token' ));
$result = $api->test('foo');
if ($api->isSuccess()) {
    var_dump($result);
} else {
    printf("Error (%d): %s\n", $api->getStatusCode(), $api->getErrorMsg());
}

该test API将使用在test.php配置文件中指定的头以及X-Auth-Token头执行HTTP请求。基本上，配置文件中指定的头与使用setHeaders函数指定的默认头合并。您可以使用配置文件中的相同头键覆盖默认头。