commonledger/commonledger-sdk

Official CommonLedger API library client for PHP

dev-master 2017-08-17 01:26 UTC

Requires

• ext-json: *
• guzzle/guzzle: 3.*

MIT

• Common Ledger

• commonledger

README

Official CommonLedger API library client for PHP

Installation

Make sure you have composer installed.

Add the following to your composer.json

{
    "require": {
        "commonledger/commonledger-sdk": "*"
    }
}

Update your dependencies

$ php composer.phar update

This package follows the PSR-0 convention names for its classes, which means you can easily integrate these classes loading in your own autoloader.

Usage

<?php

// This file is generated by Composer
require_once 'vendor/autoload.php';

// Then we instantiate a client (as shown below)

Build a client

Without any authentication

$client = new \CommonLedger\Sdk\Client();

// If you need to send options
$client = new \CommonLedger\Sdk\Client(null, $options);

OAuth 2.0 Access Token

$client = new \CommonLedger\Sdk\Client('ACCESS-TOKEN', $options);

Setting the access token after init

$client->setAccessToken('commonledger-issued-access-token');

Authentication

Authentication with the Common Ledger API is handled using the OAuth 2.0 standard managed by the auth() module.

$oauth_params = array(
    'client_id' => 'commonledger-client-id',
    'client_secret' => 'commonledger-client-secret',
    'redirect_uri' => 'http://example.com/redirect-url-used-in-setup',
    'scope' => 'requested-scope'
);

$auth = $client->auth($oauth_params);

Redirect URL

To start authorization you must redirect the user to Common Ledger using a GET request. This can be generated by calling the getRedirectUrl() method.

$state = 'foobar'; // some application state that will be passed when the user is redirected back (optional)
$ledger = array('id' => 'abc-123', 'name' => 'Widgets Ltd'); // data that can be used to setup a new ledger (optional)
$context = 'commonledger-state'; // similar to $state, but supplied back to Common Ledger (only used by connectors) (optional)
$redirect_url = $auth->getRedirectUrl($state, $ledger, $context);

echo $redirect_url; // https://login.commonledger.com/authorize?state=foobar...

Access tokens

Once the redirect has been completed you will be returned a code that is supplied to the accessToken() method to obtain an access_token and refresh_token;

$request_code = 'commonledger-issued-code';
$access_token = $auth->accessToken($request_code);

print_r($access_token);

/*
Array
(
    [access_token] => 0543c7eed8439967bc7576d4fbae9ed1b64b73d1
    [expires_in] => 1200
    [token_type] => Bearer
    [scope] => connector
    [refresh_token] => 6a49cd8a95f032110221d55cd64e5b0b95d8fd9d6
    [expires] => 2014-01-23T03:57:24+00:00
)
*/

For convenience the expires key is set to be the current time plus the expires_in value.

Refreshing access tokens

A token will typically expire 20 minutes after it is issued, (denoted by the expires_in and expires). You will need to refresh a token before you use it once it has expired.

$refresh_token = 'commonledger-issued-refresh-token';
$access_token = $auth->refreshToken($refresh_token);

// returns the same response as the accessToken() endpoint

Accessing data

Once you've obtained an access_token data can be requested via the each of the endpoint modules.

endpoint documentation tbc

Contributors

Here is a list of Contributors

Bug Reports

Report here.

Contact

Common Ledger ([e-mail])