creads/partners-api
A simple PHP client and CLI for Creads Partners API., (*1)
We recommend to read the Full API Documentation first., (*2)
| Build Status |
Code Climate |
Downloads |
Release |
 |
 |
 |
 |
, (*3)
Use the library in your project
Installation
The recommended way to install the library is through
Composer., (*4)
Install Composer:, (*5)
curl -sS https://getcomposer.org/installer | php
Run the Composer command to install the latest stable version:, (*6)
composer.phar require creads/partners-api
Usage
After installing, you need to require Composer's autoloader:, (*7)
require 'vendor/autoload.php';
First you need to instantiate the Client with an OAuthAuthentication, (*8)
use Creads\Partners\Client;
use Creads\Partners\OAuthAccessToken;
$authentication = new OAuthAuthenticationToken('CLIENT_ID', 'CLIENT_SECRET');
$client = new Client($authentication);
Or if you have an access token from somewhere else:, (*9)
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));
Get information about the API:, (*10)
$response = $client->get('/');
echo json_decode($response->getBody(), true)['version'];
//1.0.0
Get information about me:, (*11)
$response = $client->get('me');
echo json_decode($response->getBody(), true)['firstname'];
//John
Update my firstname:, (*12)
$client->put('me', [
'firstname' => 'John'
]);
Delete a comment of mine:, (*13)
$client->delete('comments/1234567891011');
Create a project:, (*14)
$client->post('projects', [
'title' => '',
'description' => '',
'organization' => '',
'firstname' => 'John',
'product' => ''
'price' => ''
]);
Upload a file:, (*15)
$response = $client->postFile('/tmp/realFilePath.png', 'wantedFileName.png');
The response will expose a Location header containing the file url. This url is what you need to reference in a resource to which you want to link this file, (*16)
$theFileUrl = $response->getHeader('Location');
$client->post('projects', [
// ...
'brief_files' => [
$theFileUrl
]
]);
Download a file:, (*17)
$client->downloadFile('https://distant-host.com/somefile.png', '/tmp/wantedFilePath.png');
Errors and exceptions handling
When HTTP errors occurs (4xx and 5xx responses) , the library throws a GuzzleHttp\Exception\ClientException object:, (*18)
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
}
}
If you prefer to disable throwing exceptions on an HTTP protocol error:, (*19)
$client = new Client([
'access_token' => $token,
'http_errors' => false
]);
$response = $client->get('/unknown-url');
if (404 == $e->getResponse()->getStatusCode()) {
//do something
}
Webhooks
You can check the validity of a webhook signature easily:, (*20)
use Creads\Partners\Webhook;
$webhook = new Webhook('your_secret');
if (!$webhook->isSignatureValid($receivedSignature, $receivedJsonBody)) {
throw new Exception('...');
}
Use the CLI application
Installation
If you don't need to use the library as a dependency but want to interract with Cread Partners API from your CLI.
You can install the binary globally with composer:, (*21)
composer global require creads/partners-api:@dev
Then add the bin directory of composer to your PATH in your ~/.bash_profile (or ~/.bashrc) like this:, (*22)
export PATH=~/.composer/vendor/bin:$PATH
You can update the application later with:, (*23)
composer global update creads/partners-api
Usage
Get some help:, (*24)
bin/partners --help
Log onto the API (needed the first time):, (*25)
bin/partners login
Avoid to type your password each time token expires, using "client_credentials" grant type:, (*26)
bin/partners login --grant-type=client_credentials
Or if you are not allowed to authenticated with "client_credentials", save your password locally:, (*27)
bin/partners login --save-password
Get a resource:, (*28)
bin/partners get /
{
"name": "Creads Partners API",
"version": "1.0.0-alpha12"
}
Including HTTP-headers in the output with -i:, (*29)
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"
}
Filtering result thanks to JSON Path (see http://goessner.net/articles/JsonPath).
For instance, get only the version number of the API:, (*30)
bin/partners get / -f '$.version'
Or get the organization I am member of:, (*31)
bin/partners get /me -f '$.member_of.*.organization'
Create a resource:, (*32)
..., (*33)
Update a resource:, (*34)
..., (*35)
Update a resource using an editor:, (*36)
bin/partners get /me | vim - | bin/partners post /me
Update a resource using Sublime Text:, (*37)
bin/partners get /me | subl - | bin/partners post /me
Wallogit.com
