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);
}

Note: when $organisationId is omitted (null), the SDK triggers a /v2/self lookup to resolve the personal organisation id, costing one extra request.

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 →