Skip to content
3.1
Go to file
Code

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
 
 
src
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

README.md

DigitalOcean PHP API Client

We present a modern DigitalOcean API v2 client for PHP.

Banner

Build Status StyleCI Status Software License Packagist Downloads Latest Version

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

Installation

This version supports PHP 7.1-7.4. To get started, simply require the project using Composer. You will also need to install either Guzzle or Buzz to enable us to send HTTP requests. Laravel users should install graham-campbell/digitalocean by Graham Campbell.

Standard Installation

Using Guzzle 6:

$ composer require toin0u/digitalocean-v2:^3.1 guzzlehttp/guzzle:^6.3.1

Using Guzzle 7:

$ composer require toin0u/digitalocean-v2:^3.1 guzzlehttp/guzzle:^7.0

Using Buzz 0.16:

$ composer require toin0u/digitalocean-v2:^3.1 kriswallsmith/buzz:^0.16

Framework Integration

Laravel 6+:

$ composer require graham-campbell/digitalocean:^7.1

Upgrading

If you are upgrading from version 2.3 to 3.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);

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 'cd2184a9-8f05-49f4-9700-293efb81c7fd'
$createdPool = $database->createConnectionPool('cd2184a9-8f05-49f4-9700-293efb81c7fd', 'my-pool', 'transaction', 1, 'defaultdb', 'doadmin');

// remove pool named 'my-pool' of cluster 'cd2184a9-8f05-49f4-9700-293efb81c7fd'
$pools = $database->removeConnectionPool('cd2184a9-8f05-49f4-9700-293efb81c7fd', 'my-pool');


// ** Only for Redis Database Clusters ** //

// return an object with a 'evictionPolicy' key for cluster '3a9e419c-e38e-40ef-8f56-09b4254b80e2'
$policy = $database->getEvictionPolicy('3a9e419c-e38e-40ef-8f56-09b4254b80e2');

// update eviction policy for cluster '3a9e419c-e38e-40ef-8f56-09b4254b80e2'
$database->updateEvictionPolicy('3a9e419c-e38e-40ef-8f56-09b4254b80e2', 'allkeys_random');


// ** Only for MySQL Database Clusters ** //

// return an object with a 'sqlMode' key for cluster 'd448b69d-3d06-411a-8ac7-c16132ba0f1e'
$mode = $database->getSqlMode('d448b69d-3d06-411a-8ac7-c16132ba0f1e');

// update sql mode for cluster 'd448b69d-3d06-411a-8ac7-c16132ba0f1e'
$database->updateSqlMode('d448b69d-3d06-411a-8ac7-c16132ba0f1e', 'ANSI,ERROR_FOR_DIVISION_BY_ZERO,NO_ENGINE_SUBSTITUTION,NO_ZERO_DATE,NO_ZERO_IN_DATE');

Domain

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

// return a collection of Domain entity
$domains = $domain->getAll();

// return the Domain entity 'foo.dk'
$domainFooDk = $domain->getByName('foo.dk');

// return the created Domain named 'bar.dk' and pointed to ip '127.0.0.1'
$created = $domain->create('bar.dk', '127.0.0.1');

// remove the domain named 'baz.dk'
$domain->remove('baz.dk');

Domain Record

// return the domain record api
$domainRecord = $client->domainRecord();

// return a collection of DomainRecord entity of the domain 'foo.dk'
$domainRecords = $domainRecord->getAll('foo.dk');

// return the DomainRecord entity 123 of the domain 'foo.dk'
$domainRecord123 = $domainRecord->getById('foo.dk', 123);

// return the created DomainRecord entity of the domain 'bar.dk'
$created = $domainRecord->create('bar.dk', 'AAAA', 'bar-name', '2001:db8::ff00:42:8329');

// return the DomainRecord entity 123 of the domain 'baz.dk' updated with new-name, new-data, priority 1, port 2, weight 3, flags 0, tag issue (name, data, priority, port, weight, flags and tag are nullable)
$updated = $domainRecord->update('baz.dk', 123, 'new-name', 'new-data', 1, 2, 3, 0, 'issue');

// remove domain record 123 of the domain 'qmx.dk'
$domainRecord->remove('qmx.dk', 123);

Droplet

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

// return a collection of Droplet entity
$droplets = $droplet->getAll();

// return a collection of Droplet neighbor to Droplet entity 123
$droplets = $droplet->getNeighborsById(123);

// return a collection of Droplet that are running on the same physical hardware
$neighbors = $droplet->getAllNeighbors();

// return the Droplet entity 123
$droplet123 = $droplet->getById(123);

// create and return the created Droplet entity
$created = $droplet->create('the-name', 'nyc1', '512mb', 449676388);

// create and return the created Droplet entity using an image slug
$created = $droplet->create('the-name', 'nyc1', '512mb', 'ubuntu-14-04-x64');

// remove the droplet 123
$droplet->remove(123);

// return a collection of Kernel entity
$kernels = $droplet->getAvailableKernels(123);

// return a collection of Image entity
$images = $droplet->getSnapshots(123);

// return a collection of Image entity
$backups = $droplet->getBackups(123);

// return a collection of Action entity of the droplet 123
$actions = $droplet->getActions(123);

// return the Action entity 456 of the droplet 123
$action123 = $droplet->getActionById(123, 456);

// reboot droplet 123 and return the Action entity
$rebooted = $droplet->reboot(123);

// power cycle droplet 123 and return the Action entity
$powerCycled = $droplet->powerCycle(123);

// shutdown droplet 123 and return the Action entity
$shutdown = $droplet->shutdown(123);

// power off droplet 123 and return the Action entity
$powerOff = $droplet->powerOff(123);

// power on droplet 123 and return the Action entity
$powerOn = $droplet->powerOn(123);

// reset password droplet 123 and return the Action entity
$passwordReseted = $droplet->passwordReset(123);

// resize droplet 123 with the image 789 and return the Action entity
$resized = $droplet->resize(123, 789);

// restore droplet 123 with the image 789 and return the Action entity
$restored = $droplet->restore(123, 789);

// rebuild droplet 123 with image 789 and return the Action entity
$rebuilt = $droplet->rebuild(123, 789);

// rename droplet 123 to 'new-name' and return the Action entity
$renamed = $droplet->rename(123, 'new-name');

// take a snapshot of droplet 123 and name it 'my-snapshot'. Returns the an Action entity
$snapshot = $droplet->snapshot(123, 'my-snapshot');

// change kernel to droplet 123 with kernel 321 and return the Action entity
$kernelChanged = $droplet->changeKernel(123, 321);

// enable IPv6 to droplet 123 and return the Action entity
$ipv6Enabled = $droplet->enableIpv6(123);

// disable backups to droplet 123 and return the Action entity
$backupsDisabled = $droplet->disableBackups(123);

// enable private networking to droplet 123 and return the Action entity
$privateNetworkingEnabled = $droplet->enablePrivateNetworking(123);

Image

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

// return a collection of Image entity
$images = $image->getAll();

// return a collection of distribution Image entity
$images = $image->getAll(['type' => 'distribution']);

// return a collection of application Image entity
$images = $image->getAll(['type' => 'application']);

// return a collection of private Image entity
$images = $image->getAll(['private' => true]);

// return a collection of private application Image entity
$images = $image->getAll(['type' => 'application', 'private' => true]);

// return the Image entity 123
$image123 = $image->getById(123);

// return the Image entity with the given image slug
$imageFoobar = $image->getBySlug('foobar');

// return the updated Image entity
$updatedImage = $image->update(123, 'new-name');

// remove the image 123
$image->remove(123);

// return the Action entity of the transferred image 123 to the given region slug
$transferredImage = $image->transfer(123, 'region-slug');

// return the Action entity 456 of the image 123
$actionImage = $image->getAction(123, 456);

Key

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

// return a collection of Key entity
$keys = $key->getAll();

// return the Key entity 123
$key123 = $key->getById(123);

// return the Key entity with the given fingerprint
$key = $key->getByFingerprint('f5:de:eb:64:2d:6a:b6:d5:bb:06:47:7f:04:4b:f8:e2');

// return the created Key entity
$createdKey = $key->create('my-key', 'ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDPrtBjQaNBwDSV3ePC86zaEWu0....');

// return the updated Key entity
$updatedKey = $key->update(123, 'new-key-name');

// return void if removed successfully
$key->remove(123);

Load Balancer

// return the load balancer api
$loadBalancer = $client->loadbalancer();

//returns a collection of Load Balancer entities
$loadBalancers = $loadBalancer->getAll();

//return a Load Balancer entity by id
$myLoadBalancer = $loadBalancer->getById('506f78a4-e098-11e5-ad9f-000f53306ae1');

/**
* updates an existing load balancer, the method will except a LoadBalancer
* entity or a load balancer representation in array form, the digitial
* Ocean API requires a full representation of your load
* balancer, any attribute that is missing will
* be reset to it's default setting.
*/
$myUpdatedLoadBalancer = $loadBalancer->update('506f78a4-e098-11e5-ad9f-000f53306ae1', $myLoadBalancer);

//create a standard load balancer that listens on port 80 and 443 with ssl passthrough enabled
$myNewLoadBalancer = $loadBalancer->create('my-new-load-balancer', 'nyc1');

Region

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

// return a collection of Region entity
$regions = $region->getAll();

Size

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

// return a collection of Size entity
$sizes = $size->getAll();

Tag

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

// return a collection of Tag entity
$tags = $tag->getAll();

// return a Tag entity by name
$tag = $tag->getByName();

// create a tag
$tag = $tag->create('awesome');

// tag resources
$tag->tagResources('awesome', [["resource_id" => "9569411", "resource_type" => "droplet"]]);

// untag resources
$tag->untagResources('awesome', [["resource_id" => "9569411", "resource_type" => "droplet"]]);

// remove tag
$tag->remove('awesome');

Volume

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

// returns the all volumes
$volumes = $volume->getAll();

// returns the all volumes by region
$volumes = $volume->getAll('nyc1');

// returns volumes by name and region
$volumes = $volume->getByNameAndRegion('example', 'nyc1');

// returns a volume by id
$myvolume = $volume->getById('506f78a4-e098-11e5-ad9f-000f53306ae1');

// returns a volumes snapshots by volume id
$mySnapshots = $volume->getSnapshots('506f78a4-e098-11e5-ad9f-000f53306ae1');

// creates a volume
$myvolume = $volume->create('example', 'Block store for examples', 10, 'nyc1');

// removes a volume by id
$volume->remove('506f78a4-e098-11e5-ad9f-000f53306ae1');

// removes a volume by name and region
$volume->remove('example', 'nyc1');

// attach a volume to a Droplet 
$volume->attach('506f78a4-e098-11e5-ad9f-000f53306ae1', 123, 'nyc1');

// detach a volume from a Droplet 
$volume->detach('506f78a4-e098-11e5-ad9f-000f53306ae1', 123, 'nyc1');

// resize a volume 
$volume->resize('506f78a4-e098-11e5-ad9f-000f53306ae1', 20, 'nyc1');

// take a snapshot of volume and name it 'my-snapshot'. Returns the Snapshot entity
$snapshot = $volume->snapshot('506f78a4-e098-11e5-ad9f-000f53306ae1', 'my-snapshot');

// get a volume action by its id 
$volume->getActionById(123, '506f78a4-e098-11e5-ad9f-000f53306ae1');

// get all actions related to a volume
$volume->getActions('506f78a4-e098-11e5-ad9f-000f53306ae1');

Contributing

We will gladly receive issue reports and review and accept pull requests, in accordance with our code of conduct and contribution guidelines!

$ make install
$ make test

Security

If you discover a security vulnerability within this package, please send an email to Graham Campbell at graham@alt-three.com or Glenn Jacobs at glenn@neondigital.co.uk. All security vulnerabilities will be promptly addressed. You may view our full security policy here.

License

DigitalOcean PHP API Client is licensed under The MIT License (MIT).

You can’t perform that action at this time.