README

php-bc4-client

Modern PHP 8.4 client for the Basecamp 4 API (which is hosted at https://3.basecampapi.com/{account_id}/... and follows the BC3 API specification).

Built on Symfony HttpClient, with a small surface area focused on what real applications need: Projects, Todolists, Todos, People, plus a complete OAuth 2.0 flow including transparent refresh-token rotation.

Features

• OAuth 2.0 web-server flow with Launchpad (launchpad.37signals.com)
• Refresh-token rotation: tokens are rotated on every refresh and persisted via a pluggable TokenStorageInterface — your application picks the storage backend (Doctrine, Redis, file, in-memory)
• Transparent token lifecycle: proactive refresh when expires_at is near, reactive refresh on 401, automatic single retry of the original request
• Rate-limit aware: exponential backoff on 429, configurable retry count
• invalid_grant detection: throws InvalidGrantException when the refresh token is rejected, signalling that a fresh user-authorization is required
• Pagination via Link: <…>; rel="next" headers, transparent for callers
• Resource-oriented API: $client->projects()->all(), $client->todos()->getInProject($id, $todolistId) etc.

Installation

composer require dmstr/php-bc4-client

Minimum Usage

use Dmstr\Bc4Client\Authentication\OAuth2Authentication;
use Dmstr\Bc4Client\Client\Bc4Client;

$auth = new OAuth2Authentication(
 clientId: 'YOUR_CLIENT_ID',
 clientSecret: 'YOUR_CLIENT_SECRET',
 appName: 'My App',
 appContact: 'ops@example.com',
 storage: $myTokenStorage, // implements TokenStorageInterface
);

$client = new Bc4Client(accountId: '6164391', authentication: $auth);

foreach ($client->projects()->all() as $project) {
 echo $project['name'], "\n";
}

Architecture

Authentication/
 AuthenticationInterface — minimal request-decoration contract
 OAuth2Authentication — Bearer token, refresh lifecycle
 TokenStorageInterface — your app implements this
 AuthorizationFlow — initial code → tokens, account discovery
Client/
 Bc4Client — entrypoint, hands out resources
Exception/
 Bc4ApiException — base exception
 InvalidGrantException — refresh token rejected
 RequestException — wrapped HTTP error
Resource/
 AbstractResource — pagination + request helper
 ProjectsResource
 TodoSetsResource
 TodolistsResource
 TodosResource
 PeopleResource

Inspired by

• schmunk42/php-bcx-client — the BC2 (BCX-API) sibling

License

MIT