hampel / linode
Wrapper for Linode API using Guzzle
Requires
- php: >=5.4.0
- guzzlehttp/guzzle: ~4.0
Requires (Dev)
- mockery/mockery: ^0.9
- phpunit/phpunit: ~4.0
README
A Linode API wrapper using Guzzle and implemented using simple Command objects
By Simon Hampel.
Thanks to Everett Griffiths for implementing additional API calls.
Installation
The recommended way of installing Hampel Linode is through Composer:
:::json
{
"require": {
"hampel/linode": "~3.1"
}
}
Note that if you intend to use this package with Laravel, we recommend installing the hampel/linode-laravel package instead, which provides a simple Laravel service provider and Facade for working with this API wrapper.
Usage
Note: v3.0 of this wrapper is not backwards compatible with v1.0 or v2.0 versions - applications using this wrapper will need to be re-written to utilise this new interface.
:::php
<?php
use Hampel\Linode\Linode;
use Hampel\Linode\Commands\TestCommand;
use Hampel\Linode\Commands\UserCommand;
use Hampel\Linode\Commands\DomainCommand;
// long-hand initialisation method
$client = new GuzzleHttp\Client();
$linode = new Linode($client, 'your api key here');
// alternative static factory
$linode = Linode::make('your api key here');
// create a command object for the Linode service to execute
// in this case, a simple echo test, API echos back parameters passed
$command = new TestCommand('echo', ['foo' => 'bar']);
// pass the command to Linode service
$response = $linode->execute($command);
var_dump($response);
// get api key
$command = new UserCommand('getapikey', ['username' => 'foo', 'password' => 'bar']);
$response = $linode->execute($command);
var_dump($response);
// create a new domain entry
$options = array("soa_email" => "soa_email@domain-name.com", "ttl_sec" => 3600);
$command = new DomainCommand('create', $options);
$response = $linode->execute($command);
var_dump($response);
// retrieve details about a domain
$response = $linode->execute(new DomainCommand('list', ['domainid' => 12345])); // specify domain id as parameter
var_dump($response);
?>
Example: Creating a New Linode
Sometimes it's not clear how the individual API commands fit together to bring up a new server. The process usually goes something like this:
- Create the Linode (this acts as a container)
- Create the primary disk (e.g. from a stack script)
- Create the swap disk
- Create the configuration profile
- Boot the Linode
Below is the outline in code. For production use, consider wrapping the command execution in try/catch blocks.
:::php
<?php
use Hampel\Linode\Linode;
use Hampel\Linode\Commands\LinodeCommand;
use Hampel\Linode\Commands\LinodeDiskCommand;
use Hampel\Linode\Commands\LinodeConfigCommand;
$linode = Linode::make('your api key here');
// Create the Linode
$response = $linode->execute(new LinodeCommand('create', [
'datacenterid' => 2, // from avail.datacenters()
'planid' => 2, // from avail.LinodePlans()
'paymentterm' => 1
]));
$linodeid = $response['LinodeID'];
// Create the Primary Disk
$response = $linode->execute(new LinodeDiskCommand('createfromstackscript', [
'linodeid' => $linodeid, // the one we just created
'stackscriptid' => 123,
'stackscriptudfresponses' => '{}',
'distributionid' => 89,
'label' => 'PrimaryDisk',
'size' => 24576
'rootpass' => 'xxxxxxxx'
]));
$primarydiskid = $response['DiskID'];
// Create the Swap Disk
$response = $linode->execute(new LinodeDiskCommand('create', [
'linodeid' => $linodeid,
'label' => 'SwapDisk',
'type' => 'swap',
'size' => 256
]));
$swapdiskid = $response['DiskID'];
// Create the Configuration Profile
$response = $linode->execute(new LinodeConfigCommand('create', [
'linodeid' => $linodeid,
'kernelid' => 138, // from avail.kernels()
'label' => 'StandardProfile',
'disklist' => "$primarydiskid,$swapdiskid,,,,,,,",
'rootdevicenum' => 1
]));
$configid = $response['ConfigID'];
// Boot the Linode
$response = $linode->execute(new LinodeCommand('boot', [
'linodeid' => $linodeid,
'configid' => $configid
]));
?>
Notes
The following calls have been implemented:
- account.*
- api.*
- avail.*
- domain.*
- domain.resource.*
- linode.*
- linode.config.*
- linode.disk.*
- linode.ip.*
- linode.job.*
- nodebalancer.*
- nodebalancer.config.*
- nodebalancer.node.*
- stackscript.*
- test.*
- user.*
TODO:
Write network tests for all commands (this may incur credit card charges for some tests!)
Unit Testing
Rename phpunit.xml.dist to phpunit.xml to set up unit testing, configure your API Key in the php section:
:::xml
<php>
<const name="API_KEY" value="Linode API Key goes here" />
</php>
To run mock tests only and ignore network tests, run: phpunit --exclude-group network
There are some additional tests which will incur credit card charges on your Linode account and as such, are disabled by
default. You can run these specific tests by running the command: phpunit --group chargeable
WARNING:
Running the chargeable group tests will incur charges on your credit card! Even though servers created by the unit tests are deleted in the cleanup process, the amount refunded will not match the amount billed! If a unit test fails, the server(s) will remain in your Linode account and you will be charged for them: in this case you must delete them manually.