Skip to main content
Disclaimer: 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.
The Upsun SDK for PHP is now available! 🎉 This library gives PHP developers a convenient way to interact programmatically with all Upsun API endpoints — the same ones used by the Upsun CLI and by the Console. Whether you’re listing organizations, managing projects, or automating platform tasks, this SDK gives you full access with minimal setup.

​
How it works

The SDK is generated from the official Upsun OpenAPI specification — the same source of truth used by the official Upsun CLI and Upsun Console. Before running the OpenAPI Generator to build the SDK, we run a PHP pre-processing script — templates/pre-processing/preprocess-schema.php. Its job is to enrich the OpenAPI schema with a bit of extra data (fields like x-*) for each endpoint method. We can’t easily inject that info directly from the Mustache templates , because in Mustache only basic if tests are possible — no transformation logic or complex operations can be performed. This script handles all the necessary transformations beforehand, so the OpenAPI Generator has everything it needs up front, while our templates stay clean, simple, and focused. The SDK is then built using OpenAPI Generator, producing:
  • Models (src/Model/): PHP representations of the Component schemas defined in the OpenAPI specification
  • APIs (src/Api/): PHP classes for each API endpoint, providing low-level methods to interact with the platform
On top of these generated classes, we provide a set of higher-level Tasks (src/Tasks/). These are handwritten by our Advocacy team and serve as the SDK’s public-facing interface, giving developers simple, intuitive methods for common actions without having to deal with the low-level Models or APIs directly. Architecture of the SDK This approach ensures the SDK stays closely aligned with the platform’s evolving API while providing a clean, developer-friendly interface, making it easier to maintain and extend over time.

​
Staying up to date

Every day, a GitHub workflow checks the official OpenAPI spec against our local version. If it finds any differences, it automatically opens a Pull Request and notifies our Advocacy team to keep the SDK aligned with the live API.

​
Usage examples

To give you an overview of what you can do with this Upsun SDK PHP, here are some examples below:

​
Installation

Install the Upsun SDK PHP via Composer: 
composer require upsun/upsun-sdk-php
Then include Composer’s autoloader in your PHP application: 
require __DIR__ . '/vendor/autoload.php';

​
Authentication

You’ll need an Upsun API token to use the SDK.
Store it securely, for example in an environment variable: 
use Upsun\UpsunConfig;
use Upsun\UpsunClient;

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

​
List organizations

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

​
List projects in an organization

$projects = $client->organizations->listProjects('<organizationId>');

​
Get a project

$project = $client->projects->get('<projectId>');

​
Create a new project

// without explicit parameters
$project = $client->projects->create(
    '<organizationId>',
    'eu-5.platform.sh',
    'Project title',
    'main',
);

​
Update a project

// with explicit parameters
$response = $client->projects->update(
    projectId: '<projectId>',
    title: 'new Title',
    description: 'Description'
);

​
Delete a project

$client->projects->delete('<projectId>');
You can find the complete example in this test-sdk.php file.

​
Clear and helpful PHPDoc

Every class, property, and method in the SDK is carefully documented.
The PHPDoc comments are written to guide you through each endpoint, model, and expected parameter, making the SDK easy to navigate with IDE autocomplete and inline hints. This means developers can explore the SDK intuitively — just type $client-> and let your IDE show you what’s available. And when a task method expects an array (for example, the $client->projects->create() call, the PHPDoc includes a detailed description of the expected array structure, so you always know exactly which keys and values to provide.

​
Coverage

  • Full API Coverage: Access every Upsun public API endpoint.
  • Simple Authentication: Use your Upsun API token to connect instantly.
  • Modern PHP Design: Compatible with PHP 8.1 and later, using readonly properties and strict typing.
  • Auto-generated Models and APIs: Consistent and always up to date with Upsun’s OpenAPI spec.
  • Comprehensive Test Suite: Every task is covered by PHPUnit tests similar to the example below.
composer run test
PHPUnit 9.6.29 by Sebastian Bergmann and contributors.

...............................................................  63 / 476 ( 13%)
............................................................... 126 / 476 ( 26%)
............................................................... 189 / 476 ( 39%)
............................................................... 252 / 476 ( 52%)
............................................................... 315 / 476 ( 66%)
............................................................... 378 / 476 ( 79%)
............................................................... 441 / 476 ( 92%)
...................................                             476 / 476 (100%)

Time: 00:00.483, Memory: 54.00 MB

OK (476 tests, 3535 assertions)

​
Contributing

Contributions are more than welcome! If you find bugs, have ideas, or want to add new API endpoints, please open a pull request or a GitHub issue. You can also reach out to the Advocacy team and other developers on our Discord community.

​
Final thoughts

This SDK marks a first step toward making Upsun’s public APIs easier to use from PHP-based projects.
It’s still experimental, but it already provides full access to our API endpoints — and it’s built to evolve alongside Upsun itself. If you’re a PHP developer building automation, tooling, or integrations on Upsun, give it a try and tell us what you think! 👉 Try it today: github.com/upsun/upsun-sdk-php

​
Coming soon: SDKs for Node.js, Python, and Go

The Upsun Advocacy team is also working on official SDKs for Node.js, Python, and Go.
Each SDK will follow the same philosophy as the PHP one — open-source, API-spec driven, and developer-friendly. Stay tuned for future announcements and beta releases on our GitHub organization and Discord server.
— The Upsun Advocacy Team
Last modified on April 14, 2026