README

Laminas API Tools 客户端模块，用于消费 API 服务。

这是版本 ^4.0 的 README 文件，仅支持 php ^8.0，使用 laminas-servicemanager v3 和 laminas-json v3。

对于版本 ^3.0，您可以在版本 3 README 中阅读，它仅支持 php ^7.1，使用 laminas-servicemanager v3 和 laminas-json v3。

对于版本 ^2.0，您可以在版本 2 README 中阅读，它仅支持 php ^7.1，使用 zend-servicemanager v3 和 zend-json v3。

对于版本 1，您可以在版本 1 README 中阅读，它仍然支持 php ^5.6|^7.0，使用 zend-servicemanager v2。

考虑升级 :)

安装

此模块的安装使用 composer。

composer require samsonasik/apigility-consumer

对于其配置，将 vendor/samsonasik/apigility-consumer/config/apigility-consumer.local.php.dist 复制到 config/autoload/apigility-consumer.local.php，并使用您的 API 主机 URL（必需）、OAuth 和/或 HTTP 身份验证设置进行配置

use Laminas\Http\Client as HttpClient;

return [
    'apigility-consumer' => [
        'api-host-url' => 'http://api.host.com',

        // null for default or array of configuration listed at https://docs.zendframework.com/zend-http/client/intro/#configuration
        'http_client_options' => null,

        // for oauth
        'oauth' => [

            //default selected client
            'grant_type'    => 'password', // or client_credentials
            'client_id'     => 'foo',
            'client_secret' => 'foo_s3cret',

            // multiple clients to be selected
            'clients' => [
                'foo' => [ // foo is client_id
                    'grant_type'    => 'password', // or client_credentials
                    'client_secret' => 'foo_s3cret',
                ],
                'bar' => [ // bar is client_id
                    'grant_type'    => 'password', // or client_credentials
                    'client_secret' => 'bar_s3cret',
                ],
            ],

        ],

        // for basic and or digest
        'auth' => [

            // default client
            HttpClient::AUTH_BASIC => [
                'username' => 'foo',
                'password' => 'foo_s3cret'
            ],

            HttpClient::AUTH_DIGEST => [
                'username' => 'foo',
                'password' => 'foo_s3cret'
            ],

            // multiple clients to be selected
            'clients' => [
                'foo' => [ // foo is key represent just like "client_id" to ease switch per-client config
                    HttpClient::AUTH_BASIC => [
                        'username' => 'foo',
                        'password' => 'foo_s3cret'
                    ],

                    HttpClient::AUTH_DIGEST => [
                        'username' => 'foo',
                        'password' => 'foo_s3cret'
                    ],
                ],
                'bar' => [ // bar is key represent just like "client_id" to ease switch per-client config
                    HttpClient::AUTH_BASIC => [
                        'username' => 'bar',
                        'password' => 'bar_s3cret'
                    ],

                    HttpClient::AUTH_DIGEST => [
                        'username' => 'bar',
                        'password' => 'bar_s3cret'
                    ],
                ],
            ],

        ],
    ],
];

然后，启用它

// config/modules.config.php
return [
    'ApigilityConsumer', // <-- register here
    'Application',
],

在 Mezzio 中使用

您可以在 Mezzio 中使用，在设置好上述本地的 config/autoload/apigility-consumer.local.php 之后，您可以将 config/mezzio.local.php.dist 复制到 config/autoload/mezzio.local.php，然后您可以使用它。

服务

1. ApigilityConsumer\Service\ClientAuthService

它用于 oauth，用法如下

use ApigilityConsumer\Service\ClientAuthService;

$client = $serviceManager->get(ClientAuthService::class);

$data = [
    'api-route-segment' => '/oauth',
    'form-request-method' => 'POST',

    'form-data' => [
        'username' => 'foo', // not required if grant_type config = 'client_credentials'
        'password' => '123', // not required if grant_type config = 'client_credentials'
    ],
];
$timeout  = 100;
$clientResult = $client->callAPI($data, $timeout);

指定 Oauth "client_id"

您可以使用 withClient() 提供来指定在 Http Auth 中使用的 client_id

$clientResult = $client->withClient('bar') // bar is "client_id" defined in clients in oauth config
                       ->callAPI($data, $timeout);

重置 Oauth "client_id"

我们可以重用客户端服务，并使用 resetClient() 使用默认的 "client_id"

$clientResult = $client->withClient('bar') // bar is "client_id" defined in clients in auth config
                       ->callAPI($data, $timeout);

$clientResultDefault = $client->resetClient()
                              ->callAPI($data, $timeout);

2. ApigilityConsumer\Service\ClientService

用于一般 API 调用，用法如下

a. 一般原始 Json 数据

use ApigilityConsumer\Service\ClientService;

$data = [
    'api-route-segment' => '/api',
    'form-request-method' => 'POST',

    'form-data' => [
        // fields that will be used as raw json to be sent
        'foo' => 'fooValue',
    ],

    // token type and access token if required
    'token_type' =>  'token type if required, for example: "Bearer"',
    'access_token' => 'access token if required',
];

$client = $serviceManager->get(ClientService::class);

$timeout  = 100;
$clientResult = $client->callAPI($data, $timeout);

b. 带上传文件

您也可以使用它上传文件到 API 服务。例如

use ApigilityConsumer\Service\ClientService;

$data['api-route-segment']   = '/api';
$data['form-request-method'] = 'POST';

$data['form-data']           = $request->getPost()->toArray();
$data['form-data']['files']  = $request->getFiles()->toArray();

/** data['form-data'] should be containst like the following
[
    'regular_key1' => 'regular_keyValue1',
    'regular_key2' => 'regular_keyValue2',

    'files' => [
        'file1' => [
            'type' => 'text/csv',
            'name' => 'file.csv',
            'tmp_name' => '/path/to/tmp/file',
            'error' => 'UPLOAD_ERR_OK',
            'size' => 123,
        ],
        'file2' => [
            'type' => 'text/csv',
            'name' => 'file2.csv',
            'tmp_name' => '/path/to/tmp/file2',
            'error' => 'UPLOAD_ERR_OK',
            'size' => 123,
        ],
    ],
]
*/

$client = $serviceManager->get(ClientService::class);

$timeout  = 100;
$clientResult = $client->callAPI($data, $timeout);

带有 Http（基本或摘要）身份验证

如果 API 调用需要基本或摘要身份验证，您可以使用 ->withHttpAuthType() 应用

use Laminas\Http\Client as HttpClient;

$clientResult = $client->withHttpAuthType(HttpClient::AUTH_BASIC)
                       ->callAPI($data, $timeout);
// OR
$clientResult = $client->withHttpAuthType(HttpClient::AUTH_DIGEST)
                       ->callAPI($data, $timeout);

这将读取我们在 config/autoload/apigility-consumer.local.php 中定义的指定的基本或摘要身份验证配置。

如果您想在 callAPI() 调用中为 Http Auth 指定自定义的用户名和密码，您可以通过 $data 指定

use Laminas\Http\Client as HttpClient;

$data = [
    'api-route-segment' => '/api',
    'form-request-method' => 'POST',

    'form-data' => [
        // fields that will be used as raw json to be sent
        'foo' => 'fooValue',
    ],

    'auth' => [
        HttpClient::AUTH_BASIC => [
            'username' => 'foo',
            'password' => 'foo_s3cret'
        ],

        HttpClient::AUTH_DIGEST => [
            'username' => 'foo',
            'password' => 'foo_s3cret'
        ],
    ],
];

$clientResult = $client->withHttpAuthType(HttpClient::AUTH_BASIC)
                       ->callAPI($data, $timeout);
// OR
$clientResult = $client->withHttpAuthType(HttpClient::AUTH_DIGEST)
                       ->callAPI($data, $timeout);

在 Http Auth 中指定 "client_id"

在 Http Auth 中，没有 "client_id" 定义的概念。在 ClientService 中，它们是代表 "client_id" 的键，以简化客户端特定 Http Auth 的切换。

您可以使用 withClient() 指定在 Http Auth 中使用的 "client_id"

$clientResult = $client->withClient('bar') // bar is "client_id" defined in clients in auth config
                       ->withHttpAuthType(HttpClient::AUTH_BASIC)
                       ->callAPI($data, $timeout);

重置 Http Auth "client_id"

我们可以重用客户端服务，并使用 resetClient() 使用默认的 "client_id"

$clientResult = $client->withClient('bar') // bar is "client_id" defined in clients in auth config
                       ->withHttpAuthType(HttpClient::AUTH_BASIC)
                       ->callAPI($data, $timeout);

$clientResultDefault = $client->resetClient()
                              ->callAPI($data, $timeout);

重置 Http Auth 类型

在应用了 HttpClient::AUTH_BASIC 或 HttpClient::AUTH_DIGEST 之后，我们可以重用客户端服务，并使用 ->resetHttpAuthType() 使用不带 Http 身份验证的正常 API 调用

$clientResultWithBasicAuth   = $client->withHttpAuthType(HttpClient::AUTH_BASIC)
                                      ->callAPI($data1, $timeout);
$clientResultWithDigestAuth  = $client->withHttpAuthType(HttpClient::AUTH_DIGEST)
                                      ->callAPI($data2, $timeout);

// RESET IT TO NORMAL WITHOUT HTTP AUTHENTICATION
$clientResultWithoutHttpAuth = $client->resetHttpAuthType()
                                      ->callAPI($data3, $timeout);

callAPI() 返回的客户端结果使用方法

《$clientResult》将是一个《ApigilityConsumer\Result\ClientResult》或《ApigilityConsumer\Result\ClientAuthResult》实例，使用这个实例，您可以

//...
$clientResult = $client->callAPI($data, $timeout);

if (! $clientResult->success) {
    var_dump($clientResult::$messages);
} else {
    var_dump($clientResult->data);
}

贡献

欢迎贡献。请阅读CONTRIBUTING.md

samsonasik / apigility-consumer

维护者

详细信息

README

安装

在 Mezzio 中使用

服务

callAPI() 返回的客户端结果使用方法

贡献