creads / partners-api
A simple PHP client and CLI for Creads Partners API
Installs: 2 595
Dependents: 0
Suggesters: 0
Security: 0
Stars: 3
Watchers: 4
Forks: 3
Open Issues: 1
Requires
- php: >=5.4.0
- flow/jsonpath: ^0.3.0
- guzzlehttp/guzzle: ^6.0
- symfony/console: >=2.7
Requires (Dev)
- phpunit/phpunit: ^4.8
This package is auto-updated.
Last update: 2020-07-22 10:01:37 UTC
README
A simple PHP client and CLI for Creads Partners API.
We recommend to read the Full API Documentation first.
Build Status | Code Climate | Downloads | Release |
---|---|---|---|
Use the library in your project
Installation
The recommended way to install the library is through Composer.
Install Composer:
curl -sS https://getcomposer.org/installer | php
Run the Composer command to install the latest stable version:
composer.phar require creads/partners-api
Usage
After installing, you need to require Composer's autoloader:
require 'vendor/autoload.php';
First you need to instantiate the Client with an OAuthAuthentication
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:
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:
$response = $client->get('/'); echo json_decode($response->getBody(), true)['version']; //1.0.0
Get information about me:
$response = $client->get('me'); echo json_decode($response->getBody(), true)['firstname']; //John
Update my firstname:
$client->put('me', [ 'firstname' => 'John' ]);
Delete a comment of mine:
$client->delete('comments/1234567891011');
Create a project:
$client->post('projects', [ 'title' => '', 'description' => '', 'organization' => '', 'firstname' => 'John', 'product' => '' 'price' => '' ]);
Upload a file:
$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
$theFileUrl = $response->getHeader('Location'); $client->post('projects', [ // ... 'brief_files' => [ $theFileUrl ] ]);
Download a file:
$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:
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:
$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:
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:
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:
export PATH=~/.composer/vendor/bin:$PATH
You can update the application later with:
composer global update creads/partners-api
Usage
Get some help:
bin/partners --help
Log onto the API (needed the first time):
bin/partners login
Avoid to type your password each time token expires, using "client_credentials" grant type:
bin/partners login --grant-type=client_credentials
Or if you are not allowed to authenticated with "client_credentials", save your password locally:
bin/partners login --save-password
Get a resource:
bin/partners get /
{ "name": "Creads Partners API", "version": "1.0.0-alpha12" }
Including HTTP-headers in the output with -i
:
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:
bin/partners get / -f '$.version'
Or get the organization I am member of:
bin/partners get /me -f '$.member_of.*.organization'
Create a resource:
...
Update a resource:
...
Update a resource using an editor:
bin/partners get /me | vim - | bin/partners post /me
Update a resource using Sublime Text:
bin/partners get /me | subl - | bin/partners post /me