README

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

Example: Register a user (white-label partners only)

The usual way to add someone to an organization or a project is the invitation flow, which emails them an invitation and lets them create their own account:

$upsunClient->invitations->createOrgInvite('<organizationId>', '<emailAddress>');

Back-channel registration exists for white-label partners importing users they already authenticate themselves. It requires a machine token -- not a user API token -- whose scope includes users:create, and the API answers 403 for any other token:

$config = new UpsunConfig(
    grantType: OAuthProvider::GRANT_CLIENT_CREDENTIALS,
    clientId: getenv('OAUTH_CLIENT_ID'),
    apiToken: getenv('OAUTH_CLIENT_SECRET'),
    scope: 'admin organizations projects:edit users:create',
);
$upsunClient = new UpsunClient($config);

$user = $upsunClient->users->create(
    username: 'john_doe',
    emailAddress: 'john.doe@partner.example.com', // as held in your own system
    providerName: 'partner-idp',
    providerSubject: '<the subject identifying them on your identity provider>',
);

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/)
Hand-maintained internal APIs and models (in src/Core/Internal/)

CAUTION: src/Api/ and src/Model/ are wiped and regenerated -- composer run spec:clean is rm -Rf src/Api/* src/Model/* docs/*, and the spec-update workflow runs it nightly. Never edit anything in those two directories: hand-written code there is deleted on the next run, and .openapi-generator-ignore cannot protect it because the removal happens before the generator sees it.

Operations that are absent from the public spec, and so cannot be generated, are written by hand under src/Core/Internal/ instead, which regeneration never touches. They extend Upsun\Api\AbstractApi to reuse the generated transport, authentication and deserialization, and are called from src/Core/Tasks/ like any generated API.

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

update your local

git fetch
git checkout main
git pull

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

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

Go on release page: https://github.com/upsun/upsun-sdk-php/releases
create a new release based on the previously created tag (Do not forget to autogenerate description in the form)
check publishing action status: https://github.com/upsun/upsun-sdk-php/actions
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.

upsun / upsun-sdk-php

Maintainers

Package info

Statistics

Security