README

A PHP client for consuming the Trello API.

Install

Via Composer

$ composer require stevenmaguire/trello-php

Usage

This guide will help you navigate configuring the client, authenticating your users and retrieving an access token, and accessing the api on their behalf.

Full client documentation is available in the API Guide.

Make sure you have secured your Trello API keys before going further. There is a handy guide for that.

This project includes a basic example. You can run this example to test your application details. Open the example file and include your key and secret, run php -S localhost:8000 -t example, visit http://localhost:8000 in your favorite browser.

Configure the client

The Trello client needs a few configuration settings to operate successfully.

Setting	Description
`key`	Required, the application key associated with your application.
`token`	Required when using the package to make authenticated API requests on behalf of a user.
`domain`	Optional, default is `https://trello.com`.
`version`	Optional, default is `1`.
`secret`	Required when using package to help get access tokens, the application secret associated with your application.
`name`	Optional. This will appear on the user facing approval screen when using package to help get access tokens.
`callbackUrl`	Required when using package to help get access tokens.
`expiration`	Required when using package to help get access tokens.
`scope`	Required when using package to help get access tokens.
`proxy`	Optional setting to declare a host to use for proxy; Read more on the Guzzle Docs.

Set configuration when creating client

$client = new Stevenmaguire\Services\Trello\Client(array(
    'callbackUrl' => 'http://your.domain/oauth-callback-url',
    'domain' => 'https://trello.com',
    'expiration' => '3days',
    'key' => 'my-application-key',
    'name' => 'My sweet trello enabled app',
    'scope' => 'read,write',
    'secret' => 'my-application-secret',
    'token'  => 'abcdefghijklmnopqrstuvwxyz',
    'version' => '1',
    'proxy' => 'tcp://localhost:8125',
));

Set multiple configuration after creating client

$client = new Stevenmaguire\Services\Trello\Client(array(
    'key' => 'my-application-key',
    'name' => 'My sweet trello enabled app',
));

$config = array(
    'callbackUrl' => 'http://your.domain/oauth-callback-url',
    'expiration' => '3days',
    'scope' => 'read,write',
);

$client->addConfig($config);

Set single configuration after creating client

$client = new Stevenmaguire\Services\Trello\Client(array(
    'key' => 'my-application-key',
    'name' => 'My sweet trello enabled app',
));

$client->addConfig('token', 'abcdefghijklmnopqrstuvwxyz');

Authenticate your users and store access token

The Trello client is capable of assisting you in walking your users through the OAuth authorization process and providing your application with access token credentials.

This package utilizes The League's OAuth1 Trello Client to provide this assistance.

Create a basic client

$client = new Stevenmaguire\Services\Trello\Client(array(
    'key' => 'my-application-key',
    'secret' => 'my-application-secret',
));

Add your application's required OAuth settings

$config = array(
    'name' => 'My sweet trello enabled app',
    'callbackUrl' => 'http://your.domain/oauth-callback-url',
    'expiration' => '3days',
    'scope' => 'read,write',
);

$client->addConfig($config);

Get authorization url, then redirect your user

$authorizationUrl = $client->getAuthorizationUrl();

header('Location: ' . $authorizationUrl);

Exchange authorization token and verifier for access token

After the user approves or denies access to your application, they will be redirected to the callback url you provided. If the user approves access, the url will include oauth_token and oauth_verifier in query string parameters.

$token = $_GET['oauth_token'];
$verifier = $_GET['oauth_verifier'];

$credentials = $client->getAccessToken($token, $verifier);
$accessToken = $credentials->getIdentifier();

If successful, $credentials with be an instance of TokenCredentials. You can store the identifier within and use to authenticate requests on behalf of that user.

Use access token to make requests

$client->addConfig('token', $accessToken);

$user = $client->getCurrentUser();

Access the API with access token

Get inventory of all entities that belong to your user

$client = new Stevenmaguire\Services\Trello\Client(array(
    'key' => 'my-application-key',
    'token' => 'your-users-access-token',
));

$boards = $client->getCurrentUserBoards();
$cards = $client->getCurrentUserCards();
$organizations = $client->getCurrentUserOrganizations();

Most of the methods available in the API Guide require entity ids to conduct business.

Handling exceptions

When handling exceptions that result during requests to Trello using the client, a Stevenmaguire\Services\Trello\Exceptions\Exception will be thrown. This exception will include information from the underlying Http request/response issues, including the response body from Trello.

try {
    $board = $client->getBoard($boardId);
} catch (Stevenmaguire\Services\Trello\Exceptions\Exception $e) {
    $code = $e->getCode(); // Http status code from response
    $reason = $e->getMessage(); // Http status reason phrase
    $error = $e->getPrevious(); // GuzzleHttp\Exception\RequestException from http client
    $body = $e->getResponseBody(); // stdClass response body from http client
}

Testing

$ ./vendor/bin/phpunit

stevenmaguire / trello-php

Maintainers

Details