Upsun SDK PHP

The official Upsun SDK for PHP. This SDK provides a PHP interface that maps to the Upsun CLI commands.

For more information, read the documentation.

CAUTION: This project is currently in Beta, meaning features and APIs may evolve over time.

Please report bugs or request new features by creating a GitHub issue.

Installation

Install the SDK via Composer:

composer require upsun/upsun-sdk-php

Then include Composer's autoloader in your PHP application:

require __DIR__ . '/vendor/autoload.php';

Authentication

With an API token (default)

You will need an Upsun API token to use this SDK. Store it securely, preferably in an environment variable.

use Upsun\UpsunConfig;
use Upsun\UpsunClient;

$config = new UpsunConfig(apiToken: getenv('UPSUN_API_TOKEN'));
$upsunClient = new UpsunClient($config);

With an OAuth2 client (client_credentials grant)

If you have a registered OAuth2 client, the SDK can authenticate with the standard client_credentials grant (RFC 6749 §4.4): the client id and secret are sent via HTTP Basic authentication, and an optional scope can be requested.

use Upsun\Core\OAuthProvider;
use Upsun\UpsunConfig;
use Upsun\UpsunClient;

$config = new UpsunConfig(
    grantType: OAuthProvider::GRANT_CLIENT_CREDENTIALS,
    clientId: getenv('OAUTH_CLIENT_ID'),
    apiToken: getenv('OAUTH_CLIENT_SECRET'), // the client secret
    scope: 'projects:read', // optional
);
$upsunClient = new UpsunClient($config);

Usage

Example: List organizations

$organizations = $upsunClient->organizations->list();

Example: List projects in an organization

$projects = $upsunClient->projects->list('<organizationId>');

Example: Redeploy an environment

$response = $upsunClient->environments->redeploy('<projectId>', '<environmentId>');

---

Development

Clone the repository and install dependencies:

git clone git@github.com:upsun/upsun-sdk-php.git
composer install

Architecture of this SDK

The SDK is built as follows:

• From the JSON specs of our API
• Using @openapitools/openapi-generator-cli
• Which generates:
  • PHP Models (in src/Model/)
  • PHP APIs (in src/Api/)
• Higher-level PHP (Facade) oriented Tasks (in src/Core/Tasks/)

Regenerating API & Model classes

API and Model classes are generated using openapi-generator-cli from the Upsun OpenAPI spec.

composer run spec:install
composer run spec:full

Contributing

Contributions are welcome!
Please open a pull request or an issue for any improvements, bug fixes, or new features.

Publishing

To generate a new version of the Upsun SDK PHP and automatically publish it on https://packagist.org

1. update your local

git fetch
git checkout main
git pull

2. check existing tags on https://github.com/upsun/upsun-sdk-php/tags
3. create a new tag from your local

git tag v<x.y.z>
git push --tag

4. Go on release page: https://github.com/upsun/upsun-sdk-php/releases
5. create a new release based on the previously created tag (Do not forget to autogenerate description in the form)
6. check publishing action status: https://github.com/upsun/upsun-sdk-php/actions
7. check new release version on https://packagist.org/packages/upsun/upsun-sdk-php

Tests

To run the tests, use:

composer install
composer run test

License

This project is licensed under the Apache License 2.0. See the LICENSE and NOTICE files for details.