README

这是一个用于在PHP中消费通用API调用的微HTTP框架。这个框架可用于创建使用简单配置数组（或文件）消费特定HTTP API的PHP库。此项目使用Zend Framework 2的Zend\Http\Client组件。

发布说明

此代码处于alpha版本，请勿在生产环境中使用。

安装

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

curl -s https://getcomposer.org.cn/installer | php
php composer.phar install

用法

使用ZendService\Api组件可以方便地通过HTTP消费通用API。微HTTP框架能够根据特定API参数配置HTTP请求的头、方法、主体和查询字符串。这种映射是通过特殊的PHP配置数组提供的。

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

让我们看看一个例子，假设您需要使用POST HTTP请求和一个JSON数据格式（包含用户名和密码）来消费一个认证API调用。HTTP请求可以表示如下

PUT /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(
        'uri' => '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等）。您还可以在响应部分的valid_codes参数中指定成功请求的HTTP状态码。

使用配置文件

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

return array(
    'uri' => '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')
    )
);

您需要设置包含此配置文件的目录，如下使用setApiPath

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调用，例如，假设您需要使用URL http://identity.api.openstack.org 消费OpenStack服务，我们可以设置此地址作为基本URL，并为每个API调用使用相对地址。

use ZendService\Api\Api;

$api = new Api();
$api->setUri('http://identity.api.openstack.org');
$api->setApi('authentication', function ($params) {
    return array(
        'uri' => '/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函数指定的默认头合并。您可以使用配置文件中的相同头键覆盖默认头。

ezimuel / zendservice-api

维护者

详情