README

一个易于使用的 PHP 客户端，用于访问 One Community API。

安装

使用 Composer

composer require onecommunity/client

请用您的 公钥 联系我们以获取您的 API 密钥。

使用方法

初始化客户端

use OneCommunity\Client;

$apiKey = "xxxxxxx";
$projectName = "yourproject";
$userId = 1;

$client = new Client($apiKey, $userId, $projectName);

// Load private key from file..
$client->loadPrivateKey("private_rsa.pem");
// ..or string
$client->setPrivateKey($privateKey);

发送请求

请参阅 示例 目录以获取有效示例。

UserRequest

返回经过验证的用户的 User 对象。非常适合测试。

use OneCommunity\Requests\UserRequest;

$request = new UserRequest;
$response = $client->send($request);

if ($response->isSuccessful()) {
    var_dump($response->getData());
}

SendTransactionalMailRequest

use OneCommunity\Requests\SendTransactionalMailRequest;

$accountId = 1; // Recipient
$transactionalMailId = 1; // Mail

$request = new SendTransactionalMailRequest($accountId, $transactionalMailId);
$request->setSubstitutions(['gift' => 'Free coffee ☕']);

$response = $client->send($request);

响应

以下 HTTP 状态码被使用

如果发生任何意外情况，将抛出 OneCommunity\Exceptions\RequestException（例如，如果 API 不返回有效的 JSON 响应）。

所有响应（除了 200 OK）都包含一个 message 属性，解释发生了什么。此外，400 Bad Requests 响应包含一个 code 属性，它可以包含以下值之一

422 Unprocessable Entity 响应的验证错误结构如下

{
    "errors": {
        "field1": [
            "error1",
            "error2"
        ],
        "field2": [
            "error3"
        ]
    }
}

安全

API 基于 JWT API，这是一个使用 JSON Web Tokens 和非对称请求签名的有效且安全的机器到机器 API。这种方法的优势包括

• 请求和响应通过安全通道发送。
• 请求只能由 API 消费者（提供不可抵赖性）签名。
• 请求只对短时间内有效（避免重放攻击）。

由于该协议的非对称性质，需要生成一个公钥/私钥对（RSA 2048 位）。可以通过以下命令生成密钥对。请将您的公钥（public_rsa.pem）发送给我们，并妥善保管您的私钥。

生成公钥/私钥对

# Generates RSA private key of 2048 bit size
openssl genrsa -out private_rsa.pem 2048

# Generates public key from the private key
openssl rsa -in private_rsa.pem -outform PEM -pubout -out public_rsa.pem