praxisnetau / serverpilot-api
A wrapper and data model for the ServerPilot API implemented in PHP.
This package is not auto-updated.
Last update: 2024-10-26 20:32:15 UTC
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