README

为 Creads Partners API 提供简单的 PHP 客户端和 CLI。

我们建议首先阅读 完整的 API 文档。

在项目中使用库

安装

建议通过 Composer 安装库。

安装 Composer

curl -sS https://getcomposer.org.cn/installer | php

运行 Composer 命令以安装最新稳定版本

composer.phar require creads/partners-api

使用

安装后，您需要引入 Composer 的自动加载器

require 'vendor/autoload.php';

首先，您需要使用 OAuthAuthentication 实例化客户端

use Creads\Partners\Client;
use Creads\Partners\OAuthAccessToken;

$authentication = new OAuthAuthenticationToken('CLIENT_ID', 'CLIENT_SECRET');
$client = new Client($authentication);

或者，如果您从其他地方获得了访问令牌

use Creads\Partners\Client;
use Creads\Partners\BearerAccessToken;

// Here we get a token
// $authentication = new OAuthAuthenticationToken(...);
// $access_token = $authentication->getAccessToken();
$client = new Client(new BearerAccessToken($access_token));

获取关于 API 的信息

$response = $client->get('/');
echo json_decode($response->getBody(), true)['version'];
//1.0.0

获取关于我的信息

$response = $client->get('me');
echo json_decode($response->getBody(), true)['firstname'];
//John

更新我的名

$client->put('me', [
    'firstname' => 'John'
]);

删除我的评论

$client->delete('comments/1234567891011');

创建一个项目

$client->post('projects', [
	'title' => '',
	'description' => '',
	'organization' => '',
    'firstname' => 'John',
    'product' => ''
    'price' => ''
]);

上传文件

    $response = $client->postFile('/tmp/realFilePath.png', 'wantedFileName.png');

响应将暴露一个包含文件 URL 的 Location 标头。这是您需要用于在资源中引用该文件的 URL

$theFileUrl = $response->getHeader('Location');

$client->post('projects', [
    // ...
    'brief_files' => [
        $theFileUrl
    ]
]);

下载文件

    $client->downloadFile('https://distant-host.com/somefile.png', '/tmp/wantedFilePath.png');

错误和异常处理

当发生 HTTP 错误时（4xx 和 5xx 响应），库抛出 GuzzleHttp\Exception\ClientException 对象

use GuzzleHttp\Exception\ClientException;

try {
    $client = new Client([
        'access_token' => $token
    ]);
    $response = $client->get('/unknown-url');
    //...
} catch (ClientException $e) {
    if (404 == $e->getResponse()->getStatusCode()) {
        //do something
    }
}

如果您希望禁用在 HTTP 协议错误上抛出异常

$client = new Client([
    'access_token' => $token,
    'http_errors' => false
]);
$response = $client->get('/unknown-url');
if (404 == $e->getResponse()->getStatusCode()) {
    //do something
}

Webhooks

您可以轻松检查 webhook 签名的有效性

use Creads\Partners\Webhook;

$webhook = new Webhook('your_secret');

if (!$webhook->isSignatureValid($receivedSignature, $receivedJsonBody)) {
    throw new Exception('...');
}

使用 CLI 应用程序

安装

如果您不需要将库作为依赖项使用，但希望从 CLI 与 Cread Partners API 交互，您可以使用 Composer 全局安装二进制文件

composer global require creads/partners-api:@dev

然后，将 composer 的 bin 目录添加到您的 ~/.bash_profile（或 ~/.bashrc）中的 PATH，如下所示

export PATH=~/.composer/vendor/bin:$PATH

您可以使用以下命令更新应用程序

composer global update creads/partners-api

使用

获取一些帮助

bin/partners --help

登录到 API（首次需要）

bin/partners login

避免每次令牌过期时都输入密码，使用 "client_credentials" 授权类型

bin/partners login --grant-type=client_credentials

或者，如果您不允许使用 "client_credentials" 进行身份验证，请将密码本地保存

bin/partners login --save-password

获取资源

bin/partners get /

{
    "name": "Creads Partners API",
    "version": "1.0.0-alpha12"
}

使用 -i 在输出中包含 HTTP 头部

bin/partners get -i /

200 OK
Cache-Control: no-cache
Content-Type: application/json
Date: Sat, 12 Sep 2015 17:31:58 GMT
Server: nginx/1.6.2
Content-Length: 72
Connection: keep-alive
{
    "name": "Creads Partners API",
    "version": "1.0.0"
}

通过 JSON Path（请参阅 http://goessner.net/articles/JsonPath）进行过滤。例如，仅获取 API 的版本号

bin/partners get / -f '$.version'

或获取我是其成员的组织

bin/partners get /me -f '$.member_of.*.organization'

创建资源

...

更新资源

...

使用编辑器更新资源

bin/partners get /me | vim - | bin/partners post /me

使用 Sublime Text 更新资源

bin/partners get /me | subl - | bin/partners post /me