Skip to content

Getting started

Requirements

  • PHP 8.5 or later
  • The SDK pulls in: symfony/http-client, symfony/http-client-contracts, nyholm/psr7, psr/{clock,http-client,http-factory,http-message,log}, jolicode/automapper, symfony/clock. All declared in composer.json.

Install

composer require welcomattic/clevercloud-php-sdk

Pick an authentication mode

The recommended path is a Personal API token (Bearer):

use CleverCloud\Sdk\Auth\Credentials;

$creds = Credentials::apiToken(getenv('CC_API_TOKEN'));

Mint the token from the Console (section "Personal API tokens").

OAuth 1.0a is also supported — pair a registered consumer with a user token / secret obtained through the 3-legged flow. The token / secret are flow outputs, not something users typically configure as env vars.

Full authentication reference →

Build a client

use CleverCloud\Sdk\ClientBuilder;

$client = (new ClientBuilder())
    ->withCredentials($creds)
    ->build();

ClientBuilder::build() raises ConfigurationException if no credentials have been set (verified in src/ClientBuilder.php line 131).

Make a call

Every resource is exposed as a property on the Client facade and lazily instantiated on first read (PHP 8.4+ property hook, see src/Client.php).

$me   = $client->self->get();                  // -> CleverCloud\Sdk\Model\User
$orgs = $client->organisations->list();        // -> list<Organisation>
$apps = $client->applications->list();         // your own apps
$apps = $client->applications->list('orga_xxx'); // an organisation's apps

foreach ($client->logs->stream('app_xxx') as $entry) {
    printf("[%s] %s\n", $entry->severity ?? 'INFO', $entry->message);
}

Every resource page in the reference lists the full method surface with verified signatures.

What happens under the hood on each request

  1. The targeted resource builds a URI via UriBuilder against the right API version (V2 / V4 / Bridge) — see src/Http/UriBuilder.php.
  2. Your Credentials object rewrites the URI if needed (Bearer rewrites every V2/V4 call to api-bridge.clever-cloud.com).
  3. Lifecycle hooks registered via ClientBuilder::onRequest() run.
  4. The request is signed (OAuth1 HMAC-SHA512) or stamped with Authorization: Bearer ....
  5. The PSR-18 client (Symfony's Psr18Client by default) sends it.
  6. On 4xx/5xx: typed ApiException subclass is thrown. On 429 with retries remaining: sleep per Retry-After then retry. On 5xx with retries remaining: exponential backoff per RetryPolicy then retry.
  7. Lifecycle hooks registered via ClientBuilder::onResponse() run.
  8. The JSON body is decoded and AutoMapper hydrates a typed DTO.

Configuration knobs and hooks → Error model →