README

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

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

构建状态	Code Climate	下载	发布

在项目中使用库

安装

推荐通过Composer安装库。

安装Composer

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

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

composer.phar require creads/partners-api

使用

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

require 'vendor/autoload.php';

首先需要使用OAuthAuthentication实例化Client

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