README

A wrapper and data model for the ServerPilot API implemented in PHP.

Requires

PHP 5.3.3 or newer
curl/curl 1.4 or newer
PHP JSON extension
an account with ServerPilot (+ valid Client ID and API Key)

Installation

You can install the API in your project either via Composer on the command-line:

composer require praxisnetau/serverpilot-api ~1.0

...or by adding it to your project composer.json file:

require: {
    "praxisnetau/serverpilot-api": "~1.0"
}

...followed by this command:

composer install

Usage

You will need to create a Client ID and API Key via your ServerPilot control panel. Once you have these, you may create an instance of the API by passing in your credentials like so:

use ServerPilot\ServerPilotAPI;

$api = ServerPilotAPI::inst('<client-id>', '<api-key>');

The API will throw an Exception if the credentials are invalid, or if it encounters any other problem, so it's a good idea to wrap your API code in a try/catch block, e.g.:

try {
    
    $api = ServerPilotAPI::inst('<client-id>', '<api-key>');
    
    $servers = $api->servers->listAll();
    
} catch (\Exception $e) {
    
    // Whoops, something went wrong!
    
}

You may also set the credentials via the config object if you like:

$api = ServerPilotAPI::inst();

$api->config()->set('client-id', '<client-id>');
$api->config()->set('api-key', '<api-key>');

Commands

The API works by routing property calls to a series of command objects. By default, these property names and methods match those given by the ServerPilot API documentation, i.e.:

$api->servers;   // For server commands
$api->sysusers;  // For system user commands
$api->apps;      // For app commands
$api->dbs;       // For database commands
$api->actions;   // For action status commands

Servers

Handles server-related operations.

$api->servers->listAll();

$api->servers->get('serverid');

$api->servers->create('name');

$api->servers->update('serverid', (boolean) $firewall, (boolean) $autoupdates);

$api->servers->delete('serverid');

System Users

Handles operations on system users.

$api->sysusers->listAll();

$api->sysusers->get('sysuserid');

$api->sysusers->create('serverid', 'username', 'password');

$api->sysusers->update('sysuserid', 'newpassword');

$api->sysusers->delete('sysuserid');

Apps

Handles operations on apps.

$api->apps->listAll();

$api->apps->get('appid');

$api->apps->create('appname', 'sysuserid', 'runtime', ['domains'], ['wordpress']);

$api->apps->update('appid', 'runtime', ['domains']);

$api->apps->delete('appid');

Databases

Handles database-related operations.

$api->dbs->listAll();

$api->dbs->get('databaseid');

$api->dbs->create('appid', 'dbname', ['name' => 'username', 'password' => 'password']);

$api->dbs->update('databaseid', ['id' => 'userid', 'password' => 'newpassword']);

$api->dbs->delete('databaseid');

Actions

Retrieve the status of an action.

$api->actions->get('actionid');

Data Model

While the API commands are powerful, it can sometimes be clumsy to issue a series of commands directly via the API. Enter the data model. Model objects are provided for each of the API command areas, including:

Action
ActionStatus
App
Database
DatabaseUser
Server
SystemUser

Rather than returning decoded JSON data, the API returns either individual instances of data model classes, or arrays of data model classes (when multiple results are returned).

These model objects are API-aware and can be manipulated directly without making a separate call to the API. All model objects have an update() and a delete() method. For example:

if ($server = $api->servers->get('<server-id>')) {
    
    $server->setFirewall(true);
    $server->setAutoUpdates(true);
    
    $server->update();  // <-- server is updated via the API
    
}

Or, consider the following:

if ($app = $api->apps->get('<app-id>')) {
    
    $app->setRuntime('php7.1');
    
    $app->addDomain('myapp.mydomain.com');
    $app->removeDomain('myapp.anotherdomain.com');
    
    $app->update();  // <-- app is updated via the API
    
}

Tired of that old app? Why not delete it!

if ($app = $api->apps->get('<app-id>')) {
    
    $app->delete();  // <-- app has been deleted via the API, be careful!
    
}

Retrieving Action Status

Every time the API performs an operation where something is changed, an Action is recorded. It can be handy to see the last action that was performed, and you can retrieve this object by calling getLastAction() on the API:

if ($action = $api->getLastAction()) {
    
    $id     = $action->getID();      // ID of the action
    $data   = $action->getData();    // data returned by the API for the action
    $object = $action->getObject();  // data model object created for the action
    
}

If you just need the ID of the last action, you can use getLastActionID():

$id = $api->getLastActionID();  // ID of the last action

You can go a step further and check the status of the action using the getStatus method, which returns an ActionStatus object:

if ($action = $api->getLastAction()) {
    
    if ($status = $action->getStatus()) {
        
        $id          = $status->getID();           // ID of the action status
        $status      = $status->getStatus();       // status text ('open', 'error', or 'success')
        $serverId    = $status->getServerID();     // ID of the server
        $dateCreated = $status->getDateCreated();  // timestamp of the status
        
        if ($status->isOpen()) {
            // The action hasn't finished yet!
        }
        
        if ($status->isError()) {
            // Whoops, something went wrong!
        }
        
        if ($status->isSuccessful()) {
            // Huzzah, it worked!
        }
        
    }
    
}

Alternatively, you can retrieve the status of the last action directly from the API using getLastActionStatus():

$status = $api->getLastActionStatus();  // returns an ActionStatus object for last action

DateTime Accessors

DateTime accessor methods are present for all properties returned as a timestamp via the API. For example:

if ($server = $api->servers->get('<server-id>')) {
    
    $lastconn = $server->getLastConnected();        // returns integer timestamp
    $datetime = $server->getLastConnectedObject();  // returns DateTime object
    
}

To Do

implement paid plan SSL functionality for Apps
expand data model to support additional functionality

praxisnetau / serverpilot-api

Maintainers

Details