DigitalOcean PHP API Client

We present a modern DigitalOcean API v2 client for PHP.

Banner

Check out the change log, releases, security policy, license, code of conduct, and contribution guidelines.

Installation

This version supports PHP 7.4-8.3. To get started, simply require the project using Composer. You will also need to install packages that "provide" psr/http-client-implementation and psr/http-factory-implementation.

Standard Installation

$ composer require "toin0u/digitalocean-v2:^4.9" \
  "guzzlehttp/guzzle:^7.8" "http-interop/http-factory-guzzle:^1.2"

Framework Integration

Laravel:

$ composer require "graham-campbell/digitalocean:^10.3"

We are decoupled from any HTTP messaging client by using PSR-7, PSR-17, PSR-18, and HTTPlug. You can visit HTTPlug for library users to get more information about installing HTTPlug related packages. The framework integration graham-campbell/gitlab is by Graham Campbell and dunglas/digital-ocean-bundle is by Kévin Dunglas.

Upgrading

If you are upgrading from version 2.3 to 3.0, or from 3.2 to 4.0, you can check out our upgrading guide. We highly recommend upgrading as soon as possible.

Examples

As of version 3.0, we will will automatically discover an HTTP client to use, from what you have available. Simply create a new DigitalOcean client, provide your access token, then you're good to go:

<?php

require_once 'vendor/autoload.php';

// create a new DigitalOcean client
$client = new DigitalOceanV2\Client();

// authenticate the client with your access token which can be
// generated at https://cloud.digitalocean.com/settings/applications
$client->authenticate('your_access_token');

Version 3.0 also has a built-in paginator, and can be used on any of the APIs which return collections. By default, the pager will internally attempt to fetch 100 entries in each request, however this can be configured by passing a 2nd parameter to the constructor. We have included an example below which will fetch all droplets:

// create a new result pager
$pager = new DigitalOceanV2\ResultPager($client);

// get all droplets as an array
$droplets = $pager->fetchAll($client->droplet(), 'getAll');

// get all droplets as a Generator which lazily yields
// new results as they become available
$droplets = $pager->fetchAllLazy($client->droplet(), 'getAll');

Account

// return the account api
$account = $client->account();

// return the Account entity
$userInformation = $account->getUserInformation();

Action

// return the action api
$action  = $client->action();

// return a collection of Action entity
$actions = $action->getAll();

// return the Action entity 123
$action123 = $action->getById(123);

App

// return the app api
$app = $client->app();

// return a collection of Apps
$apps = $app->getAll();

// return the App entity 123
$app123 = $app->getById(123);

// create a new App
$spec = [
    "name" => "sample-golang",
    "services" => [
        [
            "name" => "web",
            "github" => [
              "repo" => "digitalocean/sample-golang",
              "branch" => "branch"
            ],
            "run_command" => "bin/sample-golang",
            "environment_slug" => "go",
            "instance_size_slug" => "basic-xxs",
            "instance_count" => 2,
            "routes" => [
                [
                    "path" => "/"
                ]
            ]
        ]
    ],
    "region" => "ams"
];
$app = $app->create($spec);

// update an App with App entity 123
$app = $app->update(123, $spec);

// delete an App with App entity 123
$app->remove(123);

// retrieve App deployments with App entity 123
$deployments = $app->getAppDeployments(123);

// return an App deployment with App entity 123, deployment ID of 456
$deployment = $app->getAppDeployment(123,456);

// create an App deployment with App entity 123
$deployment = $app->createAppDeployment(123);

// cancel an App deployment
$deployment = $app->cancelAppDeployment(123,456);

// retrieve deployment logs by component for entity 123, deployment ID of 456, component name of "test_component"
$logs = $app->getDeploymentLogs(123,456,"test_component");

// retrieve aggregate deployment logs for entity 123, deployment ID of 456
$logs = $app->getAggregateDeploymentLogs(123,456);

// retrieve App regions
$regions = $app->getRegions();

// retrieve App tiers
$tiers = $app->getTiers();

// return an App tier by slug with slug name of "test_slug"
$tier = $app->getTierBySlug("test_slug");

// retrieve App instance sizes
$instance_sizes = $app->getInstanceSizes();

// return App instance size by slug with slug name of "test_slug"
$instance_size = $app->getInstanceSizeBySlug("test_slug");

Database

// return the database api
$database = $client->database();

// return a collection of DatabaseCluster entity
$clusters = $database->getAllClusters();

// return a collection of DatabaseCluster entity filtered by 'tag-name'
$clusters = $database->getAllClusters('tag-name');

// return the DatabaseCluster entity '405427f6-393a-4744-817a-2ec6c1b2e2c2'
$myCluster = $database->getClusterById('405427f6-393a-4744-817a-2ec6c1b2e2c2');

// return the created DatabaseCluster entity
$createdCluster = $database->createCluster('my-redis-cluster', 'redis', 'db-s-1vcpu-1gb', 'fra1', 1);

// return the created DatabaseCluster entity with optional parameters
$anotherCluster = $database->createCluster('my-redis-cluster', 'redis', 'db-s-1vcpu-1gb', 'fra1', 1, "5", ['tag-1', 'tag-2'], 'daf994c2-1a34-4a94-beca-f43d09f63eb6');

// resize database cluster '405427f6-393a-4744-817a-2ec6c1b2e2c2'
$database->resize('405427f6-393a-4744-817a-2ec6c1b2e2c2', 'db-s-1vcpu-2gb', 2);

// migrate database cluster '405427f6-393a-4744-817a-2ec6c1b2e2c2' to the 'lon1' region
$database->migrate('405427f6-393a-4744-817a-2ec6c1b2e2c2', 'lon1');

// remove database cluster '405427f6-393a-4744-817a-2ec6c1b2e2c2'
$database->remove('405427f6-393a-4744-817a-2ec6c1b2e2c2');

// return the DatabaseRules entity of cluster '405427f6-393a-4744-817a-2ec6c1b2e2c2'
$rules = $database->getFirewallRules('405427f6-393a-4744-817a-2ec6c1b2e2c2')

// update firewall rules of cluster '405427f6-393a-4744-817a-2ec6c1b2e2c2'
$database->updateFirewallRules('405427f6-393a-4744-817a-2ec6c1b2e2c2', [
    ["type" => 'ip_addr', "value" => '192.168.1.1'],
    ["type" => 'droplet', "value" => '163973392'],
]);

// update maintenance window of cluster '405427f6-393a-4744-817a-2ec6c1b2e2c2'
$database->updateMaintenanceWindow('405427f6-393a-4744-817a-2ec6c1b2e2c2', 'thursday', "21:00");

// return a collection of DatabaseBackup entity of cluster '405427f6-393a-4744-817a-2ec6c1b2e2c2'
$backups = $database->getBackups('405427f6-393a-4744-817a-2ec6c1b2e2c2');

// create a new database cluster based on the 'origin-cluster' cluster backup and return a DatabaseCluster entity for the newly created cluster
$restored = $database->createClusterFromBackup('cluster-from-backup', ["database_name" => 'origin-cluster', "backup_created_at" => '2020-09-14T08:11:29Z'], 'mysql', 'db-s-1vcpu-1gb', 'fra1', 1, null, ['tag-1', 'tag-2']);

// return a collection of DatabaseReplica entity for cluster '405427f6-393a-4744-817a-2ec6c1b2e2c2'
$replicas = $database->getAllReplicas('405427f6-393a-4744-817a-2ec6c1b2e2c2');

// return the DatabaseReplica enitity named 'my-replica' of cluster '405427f6-393a-4744-817a-2ec6c1b2e2c2'
$replica = $database->getReplicaByName('405427f6-393a-4744-817a-2ec6c1b2e2c2', 'my-replica');

// return the created DatabaseReplica entity of cluster '405427f6-393a-4744-817a-2ec6c1b2e2c2'
$createdReplica = $database->createReplica('405427f6-393a-4744-817a-2ec6c1b2e2c2', 'my-replica', 'db-s-1vcpu-1gb');

// remove replica named 'my-replica' of cluster '405427f6-393a-4744-817a-2ec6c1b2e2c2'
$database->removeReplica('405427f6-393a-4744-817a-2ec6c1b2e2c2', 'my-replica');

// return a collection of DatabaseUser entity for cluster '405427f6-393a-4744-817a-2ec6c1b2e2c2'
$users = $database->getAllUsers('405427f6-393a-4744-817a-2ec6c1b2e2c2');

// return the DatabaseUser entity named 'my-user' of cluster '405427f6-393a-4744-817a-2ec6c1b2e2c2'
$user = $database->getUserByName('405427f6-393a-4744-817a-2ec6c1b2e2c2', 'my-user');

// return the created DatabaseUser entity named 'my-user' of cluster '405427f6-393a-4744-817a-2ec6c1b2e2c2'
$createdUser = $database->createUser('405427f6-393a-4744-817a-2ec6c1b2e2c2', 'my-user');

// return the created DatabaseUser entity named 'my-user' of cluster '405427f6-393a-4744-817a-2ec6c1b2e2c2' with optional mysql auth plugin
$createdUser2 = $database->createUser('405427f6-393a-4744-817a-2ec6c1b2e2c2', 'my-user-2', 'mysql_native_password');

// return the updated DatabaseUser entity named 'my-user' of cluster '405427f6-393a-4744-817a-2ec6c1b2e2c2'
$updatedUser = $database->updateUserMysqlAuthMethod('405427f6-393a-4744-817a-2ec6c1b2e2c2', 'my-user-2', 'caching_sha2_password');

// remove user named 'my-user' of cluster '405427f6-393a-4744-817a-2ec6c1b2e2c2'
$database->removeUser('405427f6-393a-4744-817a-2ec6c1b2e2c2', 'my-user');

// return a collection of Database entity of cluster '405427f6-393a-4744-817a-2ec6c1b2e2c2'
$dbs = $database->getAllDatabases('405427f6-393a-4744-817a-2ec6c1b2e2c2');

// return the Database entity named 'my-database' of cluster '405427f6-393a-4744-817a-2ec6c1b2e2c2'
$db = $database->getDatabaseByName('405427f6-393a-4744-817a-2ec6c1b2e2c2', 'my-database');

// return the created Database entity named 'my-database' of cluster '405427f6-393a-4744-817a-2ec6c1b2e2c2'
$createdDb = $database->createDatabase('405427f6-393a-4744-817a-2ec6c1b2e2c2', 'my-database');

// remove the database named 'my-database' of cluster '405427f6-393a-4744-817a-2ec6c1b2e2c2'
$database->removeDatabase('405427f6-393a-4744-817a-2ec6c1b2e2c2', 'my-database');


// ** Only for PostgreSQL Database Clusters ** //

// return a collection of DatabasePool entity of cluster 'cd2184a9-8f05-49f4-9700-293efb81c7fd'
$pools = $database->getAllConnectionPools('cd2184a9-8f05-49f4-9700-293efb81c7fd');

// return the DatabasePool entity named 'my-pool' of cluster 'cd2184a9-8f05-49f4-9700-293efb81c7fd'
$pool = $database->getConnectionPoolByName('cd2184a9-8f05-49f4-9700-293efb81c7fd', 'my-pool');

// return the created DatabasePool entity for cluster