stevenmaguire / trello-php
PHP wrapper for Trello API
Fund package maintenance!
stevenmaguire
Installs: 214 384
Dependents: 1
Suggesters: 0
Security: 0
Stars: 87
Watchers: 9
Forks: 25
Open Issues: 7
Requires
- php: ^8.0
- ext-json: *
- guzzlehttp/guzzle: ^7.0
- league/oauth1-client: ^1.5
Requires (Dev)
- mockery/mockery: ~1.5
- phpunit/phpunit: ^8.0
- squizlabs/php_codesniffer: ~3.5
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.
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
Contributing
Please see CONTRIBUTING for details. You can see the current PROGRESS.
Credits
License
The MIT License (MIT). Please see License File for more information.