justijndepover / teamleader-api

PHP Client for the Teamleader API

Teamleader API

PHP Client for the Teamleader API

Caution

This application is still in development and could implement breaking changes. Please use at your own risk.

Installation

You can install the package with composer

composer require justijndepover/teamleader-api

Installing the package in Laravel

To use the plugin in Laravel applications, please refer to the Laravel usage page

Usage

Connecting to Teamleader:

// note the state param: this can be a random string. It's used as an extra layer of protection. Teamleader will return this value when connecting.
$teamleader = new Teamleader(CLIENT_ID, CLIENT_SECRET, REDIRECT_URI, STATE);
// open the teamleader login
header("Location: {$teamleader->redirectForAuthorizationUrl()}");
exit;

After connecting, Teamleader will send a request back to your redirect uri.

$teamleader = new Teamleader(CLIENT_ID, CLIENT_SECRET, REDIRECT_URI, STATE);

if ($_GET['error']) {
    // your application should handle this error
}

if ($_GET['state'] != $teamleader->getState()) {
    // state value does not match, your application should handle this error
}

$teamleader->setAuthorizationCode($_GET['code']);
$teamleader->connect();

// store these values:
$accessToken = $teamleader->getAccessToken();
$refreshToken = $teamleader->getRefreshToken();
$expiresAt = $teamleader->getTokenExpiresAt();

Your application is now connected. To start fetching data:

$teamleader = new Teamleader(CLIENT_ID, CLIENT_SECRET, REDIRECT_URI, STATE);
$teamleader->setAccessToken($accessToken);
$teamleader->setRefreshToken($refreshToken);
$teamleader->setTokenExpiresAt($expiresAt);

// fetch data:
$teamleader->crm->get();

// you should always store your tokens at the end of a call
$accessToken = $teamleader->getAccessToken();
$refreshToken = $teamleader->getRefreshToken();
$expiresAt = $teamleader->getTokenExpiresAt();

Available methods

Note that your application should have the correct scopes enabled inside the integration

This application is in an early development stage. Therefore not all resources are available as props yet. (for example: $teamleader->users->me) In the meantime it's possible to fetch every resource available through the get and post methods:

$teamleader->get('users.me');
$teamleader->get('departments.list');
$teamleader->get('departments.info', ['id' => $id]);
$teamleader->post('contacts.add', [
    // all the data
]);

Rate limiting

After each request, the rate limiting headers are available.

// returns the maximum rate limit your application can hit in 1 minute
$teamleader->getRateLimitLimit();

// returns the current limit remaining
$teamleader->getRateLimitRemaining();

// returns the datetime (UTC) when your application can make calls again, after hitting the rate limit.
$teamleader->getRateLimitReset();

How you handle rate limiting is up to you. But the application provides a helper method to ensure you never hit the limit:

$teamleader->get('contacts.info', ['id' => $id]);
// executing this function will sleep until the X-RateLimitReset header has passed, but only if the rate limit is hit.
$teamleader->ensureRateLimitingIsNotExceeded();

Security

If you find any security related issues, please open an issue or contact me directly at [email protected].

Contribution

If you wish to make any changes or improvements to the package, feel free to make a pull request.

License

The MIT License (MIT). Please see License File for more information.

teamleader-api's Issues

$teamleader->connect(); not working

followed your examples. Below error is what i get after redirect when using the authorization code and all required TeamLeader params where filled.

Error!: Error 400: Could not aquire or refresh access token: The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed.

So it fails in the acquireAccessToken method. On the below call:
post: https://focus.teamleader.eu/oauth2/access_token
params: (*** are sensored)

array(1) {
  ["form_params"]=>
  array(5) {
    ["client_id"]=>
    string(32) "***"
    ["client_secret"]=>
    string(32) "***"
    ["code"]=>
    string(896) "***"
    ["grant_type"]=>
    string(18) "authorization_code"
    ["redirect_uri"]=>
    string(101) "https%3A%2F%2F***%2Fdevelopment%2Fadmin%2Findex.php%3FPage%3DAddons%26Addon%3Dteamleader"
  }
}

Carbon dependency

Carbon\Carbon is a dependency but never specified in composer.json