echo-five/api-public-php

Echo-Five API 公共 PHP

维护者

详情

github.com/echo-five/api-public-php

源代码

安装: 32

依赖者: 0

建议者: 0

安全: 0

星标: 0

关注者: 1

分支: 0

1.0.0 2023-03-06 13:55 UTC

Requires

MIT 1f179d19025d4620abe2bc368d19e10f62d13fa2

This package is auto-updated.

Last update: 2024-10-02 19:48:42 UTC

README

License Size

这是一个用于与 Echo-Five 公共 API 通信的 PHP 库。
Echo-Five 公共 API 是我个人的 API。

菜单

要求

  • PHP 7.4 或更高版本，需要 cURL 和 JSON 扩展

安装

如何安装？

此软件包可以通过 Composer 安装

composer require echo-five/api-public-php

如何更新？

使用以下命令仅更新此软件包

composer update echo-five/api-public-php

或者

使用以下命令更新所有 Composer 软件包（包括此软件包）

composer update

如何删除？

此软件包可以通过 Composer 卸载

composer remove echo-five/api-public-php

开始使用

假设库已经通过 Composer 安装，创建一个新的空白 PHP 文件并复制以下代码

<?php

// Load Composer autoloader.
require 'vendor/autoload.php';

// Use declaration.
use EchoFiveApiPublic\EchoFiveApiPublic;

// Initialize.
$api = new EchoFiveApiPublic('api.matthieuroy.be', 'MY_API_KEY');

// Do a request.
$api->request('post', '/api/v1/test/simple', [
    'foo' => 'Bar',
    'biz' => 'Buz',
]);

// Get the request response.
$requestResponse = $api->getRequestResponse();

// Dump.
var_dump($requestResponse);

此示例存储在项目中，可以在此处下载：get-started-simple-request.php

特性

简单请求与签名请求

库允许两种类型的请求，简单请求（未签名）和签名请求（签名）。

签名请求确保发送到 API 的数据没有被修改。
虽然签名请求稍微慢一些，但它们比简单请求更安全。
收到签名请求时，API 会检查随数据一起发送的请求签名的正确性。
如果签名不匹配，则不会处理请求。

签名查询的使用非常简单！
只需在实例化库时声明与 API 密钥关联的密钥。
然后所有请求都将被签名！

// Initialize.
$api = new EchoFiveApiPublic('api.matthieuroy.be', 'MY_API_KEY', 'MY_API_SECRET');

此示例存储在项目中，可以在此处下载：get-started-signed-request.php

调试

使用 API 的问题解决并不总是容易。
库包括调试模式，以更好地了解请求是如何进行的。

调试模式允许

  • 了解请求的时间消耗（以秒为单位）。
  • 了解请求的执行次数。
  • 了解请求的执行顺序。

调试模式的使用非常简单！
只需从特定的断点开始，然后停止到另一个断点。

<?php

// Load Composer autoloader.
require 'vendor/autoload.php';

// Use declaration.
use EchoFiveApiPublic\EchoFiveApiPublic;

// Initialize.
$api = new EchoFiveApiPublic('api.matthieuroy.be', 'MY_API_KEY');

// Start the debugging mode.
$api->debugStart();

// Do a request.
$api->request('post', '/api/v1/test/simple', [
    'foo' => 'Bar',
    'biz' => 'Buz',
]);

// Stop the debugging mode.
$api->debugStop();

// Get the request response.
$requestResponse = $api->getRequestResponse();

// Dumps.
var_dump($requestResponse);
var_dump($api->debugGet());

请参阅可用方法部分以获取更多调试选项。
此示例存储在项目中，可以在此处下载：get-started-debugging.php

以下是一个调试信息的示例

// Result:
Array
(
    [requests] => Array
        (
            [time] => 0.218735
            [count] => 1
            [trace] => Array
                (
                    [2023-01-01T13:57:09.603425+01:00] => Start debug.
                    [2023-01-01T13:57:09.822565+01:00] => Request | https://api.matthieuroy.be/api/v1/test/simple
                    [2023-01-01T13:57:09.822592+01:00] => Stop debug.
                )
        )
)

可用方法

请求

此方法允许发起 API 请求。

request(string $requestType, string $requestEndpoint, array <$requestParams>, string <$requestMode>)

  • requestType 参数定义了请求的类型。
    允许的值是 GET 和 POST。
    此参数是必需的。

  • 参数 requestEndpoint 定义了要调用的端点。
    这是一个 URI，例如：/api/v1/test/simple
    此参数是必需的。

  • 参数 requestParams 定义了要发送到端点的数据。
    这是一个基于键/值的数组，默认情况下不向端点发送数据。
    此参数是可选的。

  • 参数 requestMode 定义了与请求类型一起使用的发送模式。
    允许的值是 FORM、HTTP 和 JSON（这是默认模式）。
    此参数仅支持 POST 请求类型。此参数是可选的。

此方法返回类实例本身，而不是请求的结果。
必须使用另一个方法（getRequestResponse）来获取请求结果。
为了更方便的使用，此方法是“链式”的。

示例

// Do a request and get the request response.
$requestResponse = $api->request('post', '/api/v1/test/simple')->getRequestResponse();

获取请求响应

此方法允许获取请求的响应。

getRequestResponse(bool <$decode>)

  • decode 参数定义了是否必须对请求响应进行 json 解码。
    API 以 JSON 格式回复，因此响应是一个字符串。
    decode 参数允许获取一个 PHP 对象而不是 JSON 字符串。
    decode 参数默认设置为 true。

使用示例

$requestResponse = $api->getRequestResponse();  // Return a PHP object. 
$requestResponse = $api->getRequestResponse(1); // Return a PHP object.
$requestResponse = $api->getRequestResponse(0); // Return a JSON string.

此方法返回一个 JSON 字符串或一个 PHP 对象，具体取决于传入的参数。
请求响应始终是完整的 API 响应。
以下是一个示例

// Request:
$api->request('post', '/api/v1/test/simple', [
    'foo' => 'Bar',
    'biz' => 'Buz',
]);

// Response:
stdClass Object
(
    [status] => 200
    [data] => stdClass Object
        (
            [foo] => Bar
            [biz] => Buz
        )
    [messages] => Array
        (
            [0] => stdClass Object
                (
                    [type] => info
                    [text] => Endpoint: /api/v1/test/simple
                )	
        )
)

获取请求响应状态

此方法允许直接获取请求响应中的 [status] 部分。
status 是与响应关联的 HTTP 状态码。

getRequestResponseStatus()

此方法始终返回一个字符串。

使用示例

// Get the request response status.
$requestResponseStatus = $api->getRequestResponseStatus();

获取请求响应数据

此方法允许直接获取请求响应中的 [data] 部分。

getRequestResponseData()

此方法始终返回一个 PHP 对象。

使用示例

// Get the request response data.
$requestResponseData = $api->getRequestResponseData();

获取请求响应消息

此方法允许直接获取请求响应中的 [messages] 部分。

getRequestResponseMessages()

此方法始终返回一个 PHP 数组。

使用示例

// Get the request response messages.
$requestResponseMessages = $api->getRequestResponseMessages();

获取请求信息

每个请求都是使用 PHP cURL 扩展执行的。
此方法允许获取函数 curl_getinfo() 的结果。
请参阅官方 PHP.net 网站，以获取文档。

getRequestInfo()

此方法始终返回一个 PHP 数组。

使用示例

// Get the request info.
$requestInfo = $api->getRequestInfo();

调试开始

此方法允许启动调试模式。
在此方法调用之后执行的每个请求都将被考虑用于调试。

debugStart()

此方法返回类实例本身。
为了更方便的使用，此方法是“链式”的。

示例

// Do a request and enable the debugging mode.
$api->request('post', '/api/v1/test/simple')->debugStart();

调试停止

此方法允许停止调试模式。
在此方法调用之后执行的每个请求将不会被考虑用于调试。

debugStop()

此方法返回类实例本身。
为了更方便的使用，此方法是“链式”的。

示例

// Do a request and disable the debugging mode.
$api->request('post', '/api/v1/test/simple')->debugStop();

调试获取

此方法允许获取调试数据的结果。
此方法调用不会停止调试模式，因此可以在需要时随时调用。
这是在时间 "t" 时的调试输出。

debugGet()

此方法返回一个 PHP 数组。

示例

// Start the debugging mode.
$api->debugStart();

// Do a request #1.
$api->request('post', '/api/v1/test/simple');

// Do a request #2.
$api->request('post', '/api/v1/test/simple');

// Dump the debugging data (which contains requests #1 and #2).
var_dump($api->debugGet());

// Do a request #3.
$api->request('post', '/api/v1/test/simple');

// Do a request #4.
$api->request('post', '/api/v1/test/simple');

// Stop the debugging mode.
$api->debugStop();

// Dump the debugging data (which contains requests #1, #2, #3, #4).
var_dump($api->debugGet());

调试重置

此方法允许重置调试数据的结果。
此方法调用不会停止调试模式，但它会删除直到其调用之前收集的所有数据。

debugReset()

此方法返回类实例本身。
为了更方便的使用，此方法是“链式”的。

示例 #1

// Do a request and reset the debugging data.
$api->request('post', '/api/v1/test/simple')->debugReset();

示例 #2

// Start the debugging mode.
$api->debugStart();

// Do a request #1.
$api->request('post', '/api/v1/test/simple');

// Do a request #2.
$api->request('post', '/api/v1/test/simple');

// Dump the debugging data (which contains requests #1 and #2).
var_dump($api->debugGet());

// Reset the debugging data.
$api->debugReset();

// Do a request #3.
$api->request('post', '/api/v1/test/simple');

// Do a request #4.
$api->request('post', '/api/v1/test/simple');

// Stop the debugging mode.
$api->debugStop();

// Dump the debugging data (which contains requests #3 and #4).
var_dump($api->debugGet());

许可证

MIT