From d983ee0650b5fdae2640ed23b1997ec6330b19eb Mon Sep 17 00:00:00 2001 From: Maxim Kerstens Date: Fri, 14 Oct 2016 11:45:36 +0200 Subject: [PATCH 1/6] updated docs --- README.md | 657 +++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 625 insertions(+), 32 deletions(-) diff --git a/README.md b/README.md index 1357cf8..283be5c 100644 --- a/README.md +++ b/README.md @@ -24,65 +24,658 @@ Or you can include manually: ``` ## Usage +**General** + + * [Connect](#connect) + * [Catch errors](#catch-errors) + * [Actions](#actions) + +**Servers** + + * [List all servers](#list-all-servers) + * [Retrieve an existing server](#retrieve-an-existing-server) + * [Connect a new server](#connect-a-new-server) + * [Update an existing server](#update-an-existing-server) + * [Remove an existing server](#remove-an-existing-server) + +**System users** + + * [List all system users](#list-all-system-users) + * [Retrieve an existing system user](#retrieve-an-existing-system-user) + * [Create a new system user](#create-a-new-system-user) + * [Update an existing system user](#update-an-existing-system-user) + * [Remove an existing system user](#remove-an-existing-system-user) + +**Apps** + + * [List all apps](#list-all-apps) + * [Retrieve an existing app](#retrieve-an-existing-app) + * [Create a new app](#create-a-new-app) + * [Update an existing app](#update-an-existing-app) + * [Remove an existing app](#remove-an-existing-app) + +**Databases** + + * [List all databases](#list-all-databases) + * [Retrieve an existing database](#retrieve-an-existing-database) + * [Create a new database](#create-a-new-database) + * [Update an existing database](#update-an-existing-database) + * [Remove an existing database](#remove-an-existing-database) + +**SSL** + + * [Add custom SSL to an app](#add-custom-ssl-to-an-app) + * [Remove custom SSL from an app](#remove-custom-ssl-from-an-app) + +### Connect With your API `key` and `id` from ServerPilot, set up the config values and pass them to the ServerPilot class. You may alternatively include a `'decode' => false` config value if you just want the raw JSON-encoded value returned. ```php $config = array( - 'id' => 'cid_YOURID', - 'key' => 'YOURKEY'); + 'id' => 'YOURID', + 'key' => 'YOURKEY' + ); $sp = new ServerPilot($config); ``` From there, you can call any number of functions to manage your ServerPilot servers, apps, system users, databases, etc. -###Get lists: +### Catch errors +If there's a problem with any request a `ServerPilotException` is thrown. + +You can retrieve the error message with `getMessage()` and the actual HTTP code with `getCode()`. + +```php +try { + $servers = $sp->server_list(); +} catch(ServerPilotException $e) { + echo $e->getCode() . ': ' .$e->getMessage(); +} +``` + +### Actions +Actions are a record of work done on ServerPilot resources. These can be things like the creation of an App, deploying SSL, deleting an old Database, etc. + +All methods that modify a resource will return an `actionid` which can be used to track the status of said action. + +**Possible values of an action status** + +|Status|Description | +|-------|---------------------------------------------| +|`open` |Action has not completed yet. | +|`success`|Action was completed successfully. | +|`error` |Action has completed but there were errors.| + + +```php +$sp->action_info('ACTIONID'); +``` + +```json +{ + "data": + { + "id": "g3kiiYzxPgAjbwcY", + "serverid": "4zGDDO2xg30yEeum", + "status": "success", + "datecreated": 1403138066 + } +} +``` + +### Servers + +#### List all servers + ```php $servers = $sp->server_list(); -$users = $sp->sysuser_list(); -$apps = $sp->app_list(); -$databases = $sp->database_list(); ``` -###Get info on a particular resource: +```json +{ + "data": [ + { + "id": "FqHWrrcUfRI18F0l", + "name": "www1", + "autoupdates": true, + "firewall": true, + "lastaddress": "1.2.3.4", + "lastconn": 1403130552, + "datecreated": 1403130551 + }, { + "id": "4zGDDO2xg30yEeum", + "name": "vagrant", + "autoupdates": true, + "firewall": true, + "lastaddress": "1.2.3.4", + "lastconn": 1403130554, + "datecreated": 1403130553 + }] +} +``` + + +#### Retrieve an existing server + ```php -$server = $sp->server_info('SERVERID'); -$user = $sp->sysuser_info('SYSUSERID'); -$app = $sp->app_info('APPID'); -$database = $sp->database_info('DBID'); -$action = $sp->action_info('ACTIONID'); +$server = $sp->server_info('SERVERID'); +``` + +```json +{ + "data": + { + "id": "UXOSIYrdtL4cSGp3", + "name": "www2", + "autoupdates": true, + "firewall": true, + "lastaddress": "1.2.3.4", + "lastconn": 1403130554, + "datecreated": 1403130553 + } +} ``` -###Create a resource: +#### Connect a new server + +Use this method to tell ServerPilot that you plan to connect a new server. + ```php -$server = $sp->server_create('SERVERNAME'); -$user = $sp->sysuser_create('SERVERID', 'SYSUSERNAME', 'PASSWORD'); -$app = $sp->app_create('APPNAME', 'SYSUSERID', 'RUNTIME', ['DOMAINS'], ['WORDPRESS'] ); -$database = $sp->database_create('APPID', 'DBNAME', 'DBUSER', 'DBPASSWORD'); +$server = $sp->server_create('SERVERNAME'); +``` + +When the request goes through successfully you should get this returned: + +```json +{ + "actionid": "tW2fu4hjHnsix6Rn", + "data": + { + "id": "`UXOSIYrdtL4cSGp3`", + "name": "www2", + "autoupdates": true, + "firewall": true, + "lastaddress": null, + "lastconn": null, + "datecreated": 1403130553, + "apikey": "nqXUevYSkpW09YKy7CY7PdnL14Q1HIlAfniJZwzjqNQ" + } +} ``` -The WordPress array must contain the following keys: `site_title`, `admin_user`, `admin_password`, and `admin_email` +With `data.id` and `data.apikey` you can run the serverpilot installer on the server you just registered. + +``` +$ export SERVERID=UXOSIYrdtL4cSGp3 +$ export SERVERAPIKEY=nqXUevYSkpW09YKy7CY7PdnL14Q1HIlAfniJZwzjqNQ +$ sudo apt-get update && sudo apt-get -y install wget ca-certificates && \ + sudo wget -nv -O serverpilot-installer https://download.serverpilot.io/serverpilot-installer && \ + sudo sh serverpilot-installer \ + --server-id=$SERVERID \ + --server-apikey=$SERVERAPIKEY +``` + +#### Update an existing server +There are 2 options you can change on each server; firewall and auto updates. + +Both of these options are `booleans` (if you don't want to change an option you can define it as `null`. + +```php +$response = $sp->server_update('SERVERID', 'FIREWALL':bool, 'AUTOUPDATES':bool); +``` + +```json +{ + "data": + { + "id": "UXOSIYrdtL4cSGp3", + "name": "www2", + "autoupdates": true, + "firewall": true, + "lastaddress": "1.2.3.4", + "lastconn": 1403130554, + "datecreated": 1403130553 + } +} +``` + +#### Remove an existing server -###Update a resource: ```php -$server = $sp->server_update('SERVERID', (bool)FIREWALL, (bool)SYSUPDATE); -$user = $sp->sysuser_update('SYSUSERID', 'PASSWORD'); -$app = $sp->app_update('APPID', 'RUNTIME', ['DOMAINS']); -$database = $sp->database_update('DBID', 'DBUSERID', 'PASSWORD'); +$response = $sp->server_delete('SERVERID'); ``` -###Delete a resource: +```json +{ + "data": {} +} +``` + + +### System users + +#### List all system users + +```php +$systemUsers = $sp->sysuser_list(); +``` + +```json +{ + "data": + [ + { + "id": "PdmHhsb3fnaZ2r5f", + "name": "serverpilot", + "serverid": "FqHWrrcUfRI18F0l" + }, + { + "id": "RvnwAIfuENyjUVnl", + "name": "serverpilot", + "serverid": "4zGDDO2xg30yEeum" + }] +} +``` + + +#### Retrieve an existing system user + +```php +$systemUser = $sp->sysuser_info('SERVERID'); +``` + +```json +{ + "data": + { + "id": "PPkfc1NECzvwiEBI", + "name": "derek", + "serverid": "FqHWrrcUfRI18F0l" + } +} +``` + +#### Create a new system user + +**Parameters** + +| Name | Type | Description +| ----------- | :------------: | :--------------------------------------- +| `serverid` | `string` | **Required**. The id of the Server. +| `name` | `string` | **Required**. The name of the System User. Length must be between 3 and 32 characters. Characters can be of lowercase ascii letters, digits, or a dash ('abcdefghijklmnopqrstuvwxyz0123456789-'), but must start with a lowercase ascii letter. `user-32` is a valid name, while `3po` is not. +| `password` | `string` | The password of the System User. If user has no password, they will not be able to log in with a password. No leading or trailing whitespace is allowed and the password must be at least 8 and no more than 200 characters long. + + +```php +$systemUser = $sp->sysuser_create('SERVERID', 'NAME', 'PASSWORD'); +``` + +When the request goes through successfully you should get this returned: + +```json +{ + "actionid": "nnpgQoNzSK11fuTe", + "data": + { + "id": "PPkfc1NECzvwiEBI", + "name": "derek", + "serverid": "FqHWrrcUfRI18F0l" + } +} +``` + +#### Update an existing system user + +**Parameters** + +| Name | Type | Description +| ----------- | :------------: | :--------------------------------------- +| `serverid` | `string` | **Required**. The id of the Server. +| `password` | `string` | The password of the System User. If user has no password, they will not be able to log in with a password. No leading or trailing whitespace is allowed and the password must be at least 8 and no more than 200 characters long. + +Every parameter except for app id is optional (meaning that by providing `null` nothing will be changed). + +```php +$response = $sp->sysuser_update('SERVERID', 'PASSWORD'); +``` + +```json +{ + "actionid": "OF42xCWkKcaX3qG2", + "data": + { + "id": "RvnwAIfuENyjUVnl", + "name": "serverpilot", + "serverid": "4zGDDO2xg30yEeum" + } +} +``` + +#### Remove an existing system user + +```php +$response = $sp->sysuser_delete('SYSUSERID'); +``` + +```json +{ + "actionid": "9tvygrrXZulYuizz", + "data": {} +} +``` + + +### Apps + +#### List all apps + ```php -$server = $sp->server_delete('SERVERID'); -$user = $sp->sysuser_delete('SYSUSERID'); -$app = $sp->app_delete('APPID'); -$database = $sp->database_delete('DBID'); +$apps = $sp->app_list(); ``` -###SSL functions (requires paid plan): +```json +{ + "data": [ + { + "id": "c77JD4gZooGjrF8K", + "datecreated": 1403139066, + "name": "blog", + "sysuserid": "RvnwAIfuENyjUVnl", + "domains": ["www.myblog.com", "blog.com"], + "ssl": null, + "serverid": "4zGDDO2xg30yEeum", + "runtime": "php7.0" + }, + { + "id": "B1w7yc1tfUPQLIKS", + "datecreated": 1403143012, + "name": "store", + "sysuserid": "RvnwAIfuENyjUVnl", + "domains": ["www.mystore.com", "mystore.com"], + "ssl": { + "key": "-----BEGIN PRIVATE KEY----- ...", + "cert": "-----BEGIN CERTIFICATE----- ...", + "cacerts": "-----BEGIN CERTIFICATE----- ...", + "auto": false, + "force": false + }, + "serverid": "4zGDDO2xg30yEeum", + "runtime": "php7.0" + }] +} +``` + + +#### Retrieve an existing app + +```php +$app = $sp->app_info('APPID'); +``` + +```json +{ + "data": + { + "id": "UXOSIYrdtL4cSGp3", + "name": "www2", + "autoupdates": true, + "firewall": true, + "lastaddress": "1.2.3.4", + "lastconn": 1403130554, + "datecreated": 1403130553 + } +} +``` + +#### Create a new app + +**Parameters** + + +| Name | Type | Description +| ----------- | :------------: | :--------------------------------------- +| `name` | `string` | **Required**. The nickname of the App. Length must be between 3 and 30 characters. Characters can be of lowercase ascii letters and digits. +| `sysuserid` | `string` | **Required**. The System User that will "own" this App. Since every System User is specific to a Server, this implicitly determines on which Server the App will be created. +| `runtime` | `string` | **Required**. The PHP runtime for an App. Choose from `php5.4`, `php5.5`, `php5.6`, `php7.0`, or `php7.1`. +| `domains` | `array` | An array of domains that will be used in the webserver's configuration. If you set your app's domain name to *example.com*, Nginx and Apache will be configured to listen for both *example.com* and *www.example.com*. **Note**: The complete list of domains must be included in every update to this field. + + +```php +$app = $sp->app_create('APPNAME', 'SYSUSERID', 'RUNTIME', 'DOMAINS'); +``` + +When the request goes through successfully you should get this returned: + +```json +{ + "actionid": "dIrCNoWunW92lPjw", + "data": + { + "id": "nlcN0TwdZAyNEgdp", + "datecreated": 1403143012, + "name": "gallery", + "sysuserid": "RvnwAIfuENyjUVnl", + "domains": ["www.example.com", "example.com"], + "ssl": null, + "serverid": "4zGDDO2xg30yEeum", + "runtime": "php7.0" + } +} +``` + +#### Update an existing app + +**Parameters** + +| Name | Type | Description +| --------- | :------------: | :--------------------------------------- +| `runtime` | `string` | The PHP runtime for an App. Choose from `php5.4`, `php5.5`, `php5.6`, `php7.0`, or `php7.1`. +| `domains` | `array` | An array of domains that will be used in the webserver's configuration. If you set your app's domain name to *example.com*, Nginx and Apache will be configured to listen for both *example.com* and *www.example.com*. **Note**: The complete list of domains must be included in every update to this field. + +Every parameter except for app id is optional (meaning that by providing `null` nothing will be changed). + +```php +$response = $sp->app_update('APPID', 'RUNTIME', 'DOMAINS'); +``` + +```json +{ + "actionid": "KlsNzLikw3BRvShc", + "data": + { + "id": "nlcN0TwdZAyNEgdp", + "datecreated": 1403143012, + "name": "gallery", + "sysuserid": "RvnwAIfuENyjUVnl", + "domains": ["www.example.com", "example.com"], + "ssl": null, + "serverid": "4zGDDO2xg30yEeum", + "runtime": "php5.6" + } +} +``` + +#### Remove an existing app + +```php +$response = $sp->app_delete('APPID'); +``` + +```json +{ + "actionid": "88Ypexhx28Y63eyA", + "data": {} +} +``` + + + +### Databases + +#### List all databases + +```php +$databases = $sp->database_list(); +``` + +```json +{ + "data": + [ + { + "id": "hdXkAZchuj27Hm1L", + "name": "wordpress", + "appid": "c77JD4gZooGjrF8K", + "serverid": "4zGDDO2xg30yEeum", + "user": { + "id": "vt08Qz9kjOC3RVLr", + "name": "robert" + } + } + ] +} +``` + + +#### Retrieve an existing database + +```php +$app = $sp->database_info('DBID'); +``` + +```json +{ + "data": + { + "id": "8PV1OIAlAW3jbGmM", + "name": "gallerydb", + "appid": "nlcN0TwdZAyNEgdp", + "serverid": "4zGDDO2xg30yEeum", + "user": { + "id": "k2HWtU33mpUsfOdA", + "name": "arturo" + } + } +} +``` + +#### Create a new database + +**Parameters** + + +| Name | Type | Description +| ----------- | :------------: | :--------------------------------------- +| `appid` | `string` | **Required**. The id of the App. +| `name` | `string` | **Required**. The name of the database. Length must be between 3 and 64 characters. Characters can be of lowercase ascii letters, digits, or a dash ('abcdefghijklmnopqrstuvwxyz0123456789-'). +| `username` | `string` | **Required**. The name of the Database User. Length must be at most 16 characters. +| `password` | `string` | **Required**. The password of the Database User. No leading or trailing whitespace is allowed and the password must be at least 8 and no more than 200 characters long. + + +```php +$app = $sp->database_create('APPID', 'NAME', 'USERNAME', 'PASSWORD'); +``` + +When the request goes through successfully you should get this returned: + +```json +{ + "actionid": "gPFiWP9hFNUxvT70", + "data": + { + "id": "8PV1OIAlAW3jbGmM", + "name": "gallerydb", + "appid": "nlcN0TwdZAyNEgdp", + "serverid": "4zGDDO2xg30yEeum", + "user": { + "id": "k2HWtU33mpUsfOdA", + "name": "arturo" + } + } +} +``` + +#### Update an existing database + +**Parameters** + +| Name | Type | Description +| ----------- | :------------: | :--------------------------------------- +| `appid` | `string` | **Required**. The id of the App. +| `userid` | `string` | **Required**. The id of the Database User. +| `password` | `string` | **Required**. The *new* password of the Database User. No leading or trailing whitespace is allowed and the password must be at least 8 and no more than 200 characters long. + +Every parameter except for app id is optional (meaning that by providing `null` nothing will be changed). + +```php +$response = $sp->database_update('DBID', 'USERID', 'PASSWORD'); +``` + +```json +{ + "actionid": "VfH12ukDJFv0RZAO", + "data": + { + "id": "8PV1OIAlAW3jbGmM", + "name": "gallerydb", + "appid": "nlcN0TwdZAyNEgdp", + "serverid": "4zGDDO2xg30yEeum", + "user": { + "id": "k2HWtU33mpUsfOdA", + "name": "arturo" + } + } +} +``` + +#### Remove an existing database + +```php +$response = $sp->database_delete('APPID'); +``` + +```json +{ + "actionid": "88Ypexhx28Y63eyA", + "data": {} +} +``` + +### SSL + +#### Add custom SSL to an app + + +**Parameters** + +| Name | Type | Description +| ----------- | :------------: | :--------------------------------------- +| `appid` | `string` | **Required**. The id of the App. +| `key` | `string` | **Required**. The contents of the private key. +| `cert` | `string` | **Required**. The contents of the certificate. +| `cacerts` | `string` | The contents of the CA certificate(s). If none, null is acceptable. + + +```php +$ssl = $sp->ssl_add('APPID', 'KEY', 'CERT', 'CACERTS); +``` + +```json +{ + "actionid": "BzcMNZ9sdBY62vTd", + "data": + { + "key": "-----BEGIN PRIVATE KEY----- ... -----END PRIVATE KEY-----", + "cert": "-----BEGIN CERTIFICATE----- ... -----END CERTIFICATE-----", + "cacerts": "-----BEGIN CERTIFICATE----- ... -----END CERTIFICATE-----" + } +} +``` + +#### Remove custom SSL from an app + ```php -$ssl = $sp->ssl_add('APPID', 'PRIVATEKEY', 'CERTIFICATE', 'CACERTS'); -$ssl = $sp->ssl_delete('APPID'); -$ssl = $sp->ssl_auto('APPID'); +$ssl = $sp->ssl_delete('APPID'); ``` ##Notes From 6783a2a4f95351924f8046b9f71f76e54ff11659 Mon Sep 17 00:00:00 2001 From: Maxim Kerstens Date: Fri, 14 Oct 2016 11:47:22 +0200 Subject: [PATCH 2/6] Added an exception on HTTP error --- lib/ServerPilot.php | 132 ++++++++++++++++++++++++++++------- lib/ServerPilotException.php | 14 ++++ 2 files changed, 121 insertions(+), 25 deletions(-) create mode 100644 lib/ServerPilotException.php diff --git a/lib/ServerPilot.php b/lib/ServerPilot.php index fae2386..11f555e 100644 --- a/lib/ServerPilot.php +++ b/lib/ServerPilot.php @@ -48,7 +48,9 @@ public function server_list() { * Create a new server * * @param string Nickname of the server. Must be 1 to 255 characters in length, may only contain the characters abcdefghijklmnopqrstuvwxyz0123456789.- - */ + * + * @return mixed + */ public function server_create( $name ) { $params['name'] = $name; @@ -59,7 +61,9 @@ public function server_create( $name ) { * Retrieve information on an existing server * * @param string ID of the server - */ + * + * @return mixed + */ public function server_info( $id ) { return $this->_send_request( "servers/$id" ); } @@ -68,7 +72,9 @@ public function server_info( $id ) { * Delete a server * * @param string ID of the server - */ + * + * @return mixed + */ public function server_delete( $id ) { return $this->_send_request( "servers/$id", array(), ServerPilot::SP_HTTP_METHOD_DELETE ); } @@ -79,7 +85,9 @@ public function server_delete( $id ) { * @param string ID of the server * @param bool "Enabled" state of the Server firewall (False = firewall is not enabled) * @param bool "Enabled" state of automatic system updates (False = automatic system updates are not enabled) - */ + * + * @return mixed + */ public function server_update( $id, $firewall = null, $autoupdates = null ) { if( $firewall ) $params['firewall'] = $firewall; @@ -103,7 +111,9 @@ public function sysuser_list() { * @param string ID of the server * @param string Name of the new user. Must be 3 to 32 characters in length, may only contain the characters abcdefghijklmnopqrstuvwxyz0123456789.- * @param string Password of the new user. If user has no password, they will not be able to log in. No leading or trailing whitespace is allowed, must be at least 8 characters in length. - */ + * + * @return mixed + */ public function sysuser_create( $id, $name, $password = NULL ) { $params = array( 'serverid' => $id, @@ -118,7 +128,9 @@ public function sysuser_create( $id, $name, $password = NULL ) { * Retrieve information on an existing system user * * @param string ID of the system user - */ + * + * @return mixed + */ public function sysuser_info( $id ) { return $this->_send_request( "sysusers/$id" ); } @@ -127,7 +139,9 @@ public function sysuser_info( $id ) { * Delete a system user * * @param string ID of the system user - */ + * + * @return mixed + */ public function sysuser_delete( $id ) { return $this->_send_request( "sysusers/$id", array(), ServerPilot::SP_HTTP_METHOD_DELETE ); } @@ -137,7 +151,9 @@ public function sysuser_delete( $id ) { * * @param string ID of the system user * @param string New password of the App user. No leading or trailing whitespace is allowed, must be at least 8 characters in length. - */ + * + * @return mixed + */ public function sysuser_update( $id, $password ) { $params['password'] = $password; @@ -180,7 +196,9 @@ public function app_create( $name, $sysuserid, $runtime, $domains = array(), $wo * Retrieve information on an existing app * * @param string ID of the app - */ + * + * @return mixed + */ public function app_info( $id ) { return $this->_send_request( "apps/$id" ); } @@ -189,7 +207,9 @@ public function app_info( $id ) { * Delete an app * * @param string ID of the app - */ + * + * @return mixed + */ public function app_delete( $id ) { return $this->_send_request( "apps/$id", array(), ServerPilot::SP_HTTP_METHOD_DELETE ); } @@ -202,7 +222,9 @@ public function app_delete( $id ) { * @param array An array of domains that will be used in the webserver's configuration. * If you set your app's domain name to example.com, Nginx and Apache will be configured to listen for both example.com and www.example.com. * Note: The complete list of domains must be included in every update to this field. - */ + * + * @return mixed + */ public function app_update( $id, $runtime = NULL, $domains = NULL ) { if( $runtime ) $params['runtime'] = $runtime; @@ -233,7 +255,8 @@ public function ssl_auto( $id ) { * @param string Contents of the private key * @param string Contents of the certificate * @param string Contents of the CA certificate(s). If none, NULL is acceptable. - */ + * + * @return mixed */ public function ssl_add( $id, $key, $cert, $cacerts = NULL) { $params = array( 'key' => $key, @@ -247,7 +270,9 @@ public function ssl_add( $id, $key, $cert, $cacerts = NULL) { * Delete an SSL cert for an app - requires Coach or Business plan * * @param string ID of the app - */ + * + * @return mixed + */ public function ssl_delete( $id ) { return $this->_send_request( "apps/$id/ssl", array(), ServerPilot::SP_HTTP_METHOD_DELETE ); } @@ -264,7 +289,9 @@ public function database_list() { * Retrieve information on an existing database * * @param string ID of the database - */ + * + * @return mixed + */ public function database_info( $id ) { return $this->_send_request( "dbs/$id" ); } @@ -276,7 +303,9 @@ public function database_info( $id ) { * @param string Name of the database. Length must be between 3 and 64 characters, may contain lowercase ascii letters, digits, or a dash. * @param string Name of database user * @param string Password for database user. Length must be between 1 and 16 characters, may contain lowercase ascii letters, digits, an underscore, or a dash. - */ + * + * @return mixed + */ public function database_create( $id, $name, $username, $password ) { $user = new stdClass(); $user->name = $username; @@ -294,7 +323,9 @@ public function database_create( $id, $name, $username, $password ) { * Delete a database * * @param string ID of the database - */ + * + * @return mixed + */ public function database_delete( $id ) { return $this->_send_request( "dbs/$id", array(), ServerPilot::SP_HTTP_METHOD_DELETE ); } @@ -305,7 +336,9 @@ public function database_delete( $id ) { * @param string ID of the database * @param string ID for the database user being updated * @param string New password for this database user. Length must be between 1 and 16 characters, may contain lowercase ascii letters, digits, an underscore, or a dash - */ + * + * @return mixed + */ public function database_update( $id, $userid, $password ) { $user = new stdClass(); $user->id = $userid; @@ -320,12 +353,21 @@ public function database_update( $id, $userid, $password ) { * Retrieve information on a particular action * * @param string ID of the action - */ + * + * @return mixed + */ public function action_info( $id ) { return $this->_send_request( "actions/$id" ); } - - + + /** + * @param string $url_segs + * @param array array $params + * @param string string $http_method + * + * @return mixed + * @throws \ServerPilotException + */ private function _send_request( $url_segs, $params = array(), $http_method = 'get' ) { // Initialize and configure the request @@ -352,10 +394,50 @@ private function _send_request( $url_segs, $params = array(), $http_method = 'ge curl_close( $req ); - // Decode JSON by default - if( $this->decode ) - return json_decode( $response ); - else - return $response; + // Everything when fine + if($http_status == 200) + { + // Decode JSON by default + if( $this->decode ) + return json_decode( $response ); + else + return $response; + } + + // Some error occured + $data = json_decode( $response ); + + // The error was provided by serverpilot + if(property_exists($response, 'error')) + throw new ServerPilotException($data->error, $http_status); + + // No error as provided, pick a default + switch($http_status) + { + case 400: + throw new ServerPilotException('We couldn\'t understand your request. Typically missing a parameter or header.', $http_status); + break; + case 401: + throw new ServerPilotException('Either no authentication credentials were provided or they are invalid.', $http_status); + break; + case 402: + throw new ServerPilotException('Method is restricted to users on the Coach or Business plan.', $http_status); + break; + case 403: + throw new ServerPilotException('Forbidden.', $http_status); + break; + case 404: + throw new ServerPilotException('You requested a resource that does not exist.', $http_status); + break; + case 409: + throw new ServerPilotException('Typically when trying creating a resource that already exists.', $http_status); + break; + case 500: + throw new ServerPilotException('Something unexpected happened on ServerPilot\'s end.', $http_status); + break; + default: + throw new ServerPilotException('Unknown error.', $http_status); + break; + } } } diff --git a/lib/ServerPilotException.php b/lib/ServerPilotException.php new file mode 100644 index 0000000..f10652d --- /dev/null +++ b/lib/ServerPilotException.php @@ -0,0 +1,14 @@ + https://github.com/daverogers/serverpilot-php + * @link https://packagist.org/packages/daverogers/serverpilot-php + * @version 1.0.2 + * @author Maxim Kestens + */ +class ServerPilotException extends Exception +{ + +} \ No newline at end of file From 9e9003261bb110caeb1f5b10e6da68811a5db784 Mon Sep 17 00:00:00 2001 From: Maxim Kerstens Date: Fri, 14 Oct 2016 11:56:07 +0200 Subject: [PATCH 3/6] updated docs to reflect autoSSL and the wordpress parameter --- README.md | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 283be5c..7562aa8 100644 --- a/README.md +++ b/README.md @@ -438,10 +438,11 @@ $app = $sp->app_info('APPID'); | `sysuserid` | `string` | **Required**. The System User that will "own" this App. Since every System User is specific to a Server, this implicitly determines on which Server the App will be created. | `runtime` | `string` | **Required**. The PHP runtime for an App. Choose from `php5.4`, `php5.5`, `php5.6`, `php7.0`, or `php7.1`. | `domains` | `array` | An array of domains that will be used in the webserver's configuration. If you set your app's domain name to *example.com*, Nginx and Apache will be configured to listen for both *example.com* and *www.example.com*. **Note**: The complete list of domains must be included in every update to this field. +| `wordpress` | `array` | An array containing the following keys: ` site_title` , ` admin_user` , ` admin_password` , and ` admin_email` ```php -$app = $sp->app_create('APPNAME', 'SYSUSERID', 'RUNTIME', 'DOMAINS'); +$app = $sp->app_create('APPNAME', 'SYSUSERID', 'RUNTIME', 'DOMAINS', 'WORDPRESS'); ``` When the request goes through successfully you should get this returned: @@ -678,6 +679,18 @@ $ssl = $sp->ssl_add('APPID', 'KEY', 'CERT', 'CACERTS); $ssl = $sp->ssl_delete('APPID'); ``` +#### Enable AutoSSL for an app + +AutoSSL can only be enabled when an AutoSSL certificate is available for an app. + +Additionally, AutoSSL cannot be enabled when an app currently has a custom SSL certificate. To enable AutoSSL when an app is already using a custom SSL, first delete the app's custom SSL certificate. + +**Note** that disabling AutoSSL is not done through this API call but instead is done by deleting SSL from the app. + +```php +$ssl = $sp->ssl_auto('APPID'); +``` + ##Notes ServerPilot site: [https://serverpilot.io/](https://serverpilot.io) From 00b318ae5b7436ef6ef0ba0c76384410c03fa7fe Mon Sep 17 00:00:00 2001 From: Maxim Kerstens Date: Fri, 14 Oct 2016 11:57:11 +0200 Subject: [PATCH 4/6] add auto ssl link --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index 7562aa8..3acc0e9 100644 --- a/README.md +++ b/README.md @@ -66,6 +66,7 @@ Or you can include manually: * [Add custom SSL to an app](#add-custom-ssl-to-an-app) * [Remove custom SSL from an app](#remove-custom-ssl-from-an-app) + * [Enable AutoSSL for an app](#enable-autossl-for-an-app) ### Connect From 4d8ac314aaa80ab3fad9e550eb81ed6e978f3e52 Mon Sep 17 00:00:00 2001 From: Maxim Kerstens Date: Fri, 14 Oct 2016 12:00:01 +0200 Subject: [PATCH 5/6] correct formatting issues --- README.md | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 3acc0e9..e4aa361 100644 --- a/README.md +++ b/README.md @@ -8,19 +8,19 @@ This simple PHP API client binds to ServerPilot's RESTful [API](https://github.c You can install the bindings via [Composer](http://getcomposer.org/). Add this to your `composer.json`: ```json - { - "require": { - "daverogers/serverpilot-php": "1.*" - } +{ + "require": { + "daverogers/serverpilot-php": "1.*" } +} ``` ...and then install ``` - composer.phar install +composer.phar install ``` Or you can include manually: ```php - include_once('/path/to/this/lib/ServerPilot.php'); +include_once('/path/to/this/lib/ServerPilot.php'); ``` ## Usage @@ -695,7 +695,11 @@ $ssl = $sp->ssl_auto('APPID'); ##Notes ServerPilot site: [https://serverpilot.io/](https://serverpilot.io) + ServerPilot's API doc: [https://github.com/ServerPilot/API](https://github.com/ServerPilot/API) + This project's Packagist link: [https://packagist.org/packages/daverogers/serverpilot-php](https://packagist.org/packages/daverogers/serverpilot-php) + Getting started with Composer: [https://getcomposer.org/doc/00-intro.md](https://getcomposer.org/doc/00-intro.md) + If this isn't your style, check out James West's PHP lib here: [https://github.com/jameswestnz/ServerPilot-API-PHP-Wrapper](https://github.com/jameswestnz/ServerPilot-API-PHP-Wrapper) From 70ca4f109fad0f9adbe82b9b8352dfbd079ffcc5 Mon Sep 17 00:00:00 2001 From: Maxim Kerstens Date: Wed, 19 Oct 2016 13:01:24 +0200 Subject: [PATCH 6/6] Correct spacing --- README.md | 376 ++++++++++++++++++++++---------------------- lib/ServerPilot.php | 6 +- 2 files changed, 193 insertions(+), 189 deletions(-) diff --git a/README.md b/README.md index e4aa361..3fe2a1c 100644 --- a/README.md +++ b/README.md @@ -114,13 +114,13 @@ $sp->action_info('ACTIONID'); ```json { - "data": - { - "id": "g3kiiYzxPgAjbwcY", - "serverid": "4zGDDO2xg30yEeum", - "status": "success", - "datecreated": 1403138066 - } + "data": + { + "id": "g3kiiYzxPgAjbwcY", + "serverid": "4zGDDO2xg30yEeum", + "status": "success", + "datecreated": 1403138066 + } } ``` @@ -134,24 +134,27 @@ $servers = $sp->server_list(); ```json { - "data": [ - { - "id": "FqHWrrcUfRI18F0l", - "name": "www1", - "autoupdates": true, - "firewall": true, - "lastaddress": "1.2.3.4", - "lastconn": 1403130552, - "datecreated": 1403130551 - }, { - "id": "4zGDDO2xg30yEeum", - "name": "vagrant", - "autoupdates": true, - "firewall": true, - "lastaddress": "1.2.3.4", - "lastconn": 1403130554, - "datecreated": 1403130553 - }] + "data": + [ + { + "id": "FqHWrrcUfRI18F0l", + "name": "www1", + "autoupdates": true, + "firewall": true, + "lastaddress": "1.2.3.4", + "lastconn": 1403130552, + "datecreated": 1403130551 + }, + { + "id": "4zGDDO2xg30yEeum", + "name": "vagrant", + "autoupdates": true, + "firewall": true, + "lastaddress": "1.2.3.4", + "lastconn": 1403130554, + "datecreated": 1403130553 + } + ] } ``` @@ -164,16 +167,16 @@ $server = $sp->server_info('SERVERID'); ```json { - "data": - { - "id": "UXOSIYrdtL4cSGp3", - "name": "www2", - "autoupdates": true, - "firewall": true, - "lastaddress": "1.2.3.4", - "lastconn": 1403130554, - "datecreated": 1403130553 - } + "data": + { + "id": "UXOSIYrdtL4cSGp3", + "name": "www2", + "autoupdates": true, + "firewall": true, + "lastaddress": "1.2.3.4", + "lastconn": 1403130554, + "datecreated": 1403130553 + } } ``` @@ -189,17 +192,16 @@ When the request goes through successfully you should get this returned: ```json { - "actionid": "tW2fu4hjHnsix6Rn", + "actionid": "tW2fu4hjHnsix6Rn", "data": { - "id": "`UXOSIYrdtL4cSGp3`", - "name": "www2", - "autoupdates": true, - "firewall": true, - "lastaddress": null, - "lastconn": null, - "datecreated": 1403130553, - "apikey": "nqXUevYSkpW09YKy7CY7PdnL14Q1HIlAfniJZwzjqNQ" + "id": "`UXOSIYrdtL4cSGp3`", + "name": "www2", + "autoupdates": true, "firewall": true, + "lastaddress": null, + "lastconn": null, + "datecreated": 1403130553, + "apikey": "nqXUevYSkpW09YKy7CY7PdnL14Q1HIlAfniJZwzjqNQ" } } ``` @@ -227,16 +229,16 @@ $response = $sp->server_update('SERVERID', 'FIREWALL':bool, 'AUTOUPDATES':boo ```json { - "data": - { - "id": "UXOSIYrdtL4cSGp3", - "name": "www2", - "autoupdates": true, - "firewall": true, - "lastaddress": "1.2.3.4", - "lastconn": 1403130554, - "datecreated": 1403130553 - } + "data": + { + "id": "UXOSIYrdtL4cSGp3", + "name": "www2", + "autoupdates": true, + "firewall": true, + "lastaddress": "1.2.3.4", + "lastconn": 1403130554, + "datecreated": 1403130553 + } } ``` @@ -263,18 +265,19 @@ $systemUsers = $sp->sysuser_list(); ```json { - "data": - [ - { - "id": "PdmHhsb3fnaZ2r5f", - "name": "serverpilot", - "serverid": "FqHWrrcUfRI18F0l" - }, - { - "id": "RvnwAIfuENyjUVnl", - "name": "serverpilot", - "serverid": "4zGDDO2xg30yEeum" - }] +"data": + [ + { + "id": "PdmHhsb3fnaZ2r5f", + "name": "serverpilot", + "serverid": "FqHWrrcUfRI18F0l" + }, + { + "id": "RvnwAIfuENyjUVnl", + "name": "serverpilot", + "serverid": "4zGDDO2xg30yEeum" + } + ] } ``` @@ -287,11 +290,11 @@ $systemUser = $sp->sysuser_info('SERVERID'); ```json { - "data": - { - "id": "PPkfc1NECzvwiEBI", - "name": "derek", - "serverid": "FqHWrrcUfRI18F0l" + "data": + { + "id": "PPkfc1NECzvwiEBI", + "name": "derek", + "serverid": "FqHWrrcUfRI18F0l" } } ``` @@ -315,12 +318,12 @@ When the request goes through successfully you should get this returned: ```json { - "actionid": "nnpgQoNzSK11fuTe", - "data": + actionid": "nnpgQoNzSK11fuTe", + data": { - "id": "PPkfc1NECzvwiEBI", - "name": "derek", - "serverid": "FqHWrrcUfRI18F0l" + id": "PPkfc1NECzvwiEBI", + "name": "derek", + "serverid": "FqHWrrcUfRI18F0l" } } ``` @@ -342,12 +345,12 @@ $response = $sp->sysuser_update('SERVERID', 'PASSWORD'); ```json { - "actionid": "OF42xCWkKcaX3qG2", + "actionid": "OF42xCWkKcaX3qG2", "data": { - "id": "RvnwAIfuENyjUVnl", - "name": "serverpilot", - "serverid": "4zGDDO2xg30yEeum" + "id": "RvnwAIfuENyjUVnl", + "name": "serverpilot", + "serverid": "4zGDDO2xg30yEeum" } } ``` @@ -360,8 +363,8 @@ $response = $sp->sysuser_delete('SYSUSERID'); ```json { - "actionid": "9tvygrrXZulYuizz", - "data": {} + "actionid": "9tvygrrXZulYuizz", + "data": {} } ``` @@ -376,33 +379,34 @@ $apps = $sp->app_list(); ```json { - "data": [ - { - "id": "c77JD4gZooGjrF8K", - "datecreated": 1403139066, - "name": "blog", - "sysuserid": "RvnwAIfuENyjUVnl", - "domains": ["www.myblog.com", "blog.com"], - "ssl": null, - "serverid": "4zGDDO2xg30yEeum", - "runtime": "php7.0" - }, - { - "id": "B1w7yc1tfUPQLIKS", - "datecreated": 1403143012, - "name": "store", - "sysuserid": "RvnwAIfuENyjUVnl", - "domains": ["www.mystore.com", "mystore.com"], - "ssl": { - "key": "-----BEGIN PRIVATE KEY----- ...", + "data": + [ + { + "id": "c77JD4gZooGjrF8K", + "datecreated": 1403139066, + "name": "blog", + "sysuserid": "RvnwAIfuENyjUVnl", + "domains": ["www.myblog.com", "blog.com"], + "ssl": null, + "serverid": "4zGDDO2xg30yEeum", + "runtime": "php7.0" + }, + { + "id": "B1w7yc1tfUPQLIKS", + "datecreated": 1403143012, + "name": "store", + "sysuserid": "RvnwAIfuENyjUVnl", + "domains": ["www.mystore.com", "mystore.com"], + "ssl": { "key": "-----BEGIN PRIVATE KEY----- ...", "cert": "-----BEGIN CERTIFICATE----- ...", "cacerts": "-----BEGIN CERTIFICATE----- ...", "auto": false, "force": false - }, - "serverid": "4zGDDO2xg30yEeum", - "runtime": "php7.0" - }] + }, + "serverid": "4zGDDO2xg30yEeum", + "runtime": "php7.0" + } + ] } ``` @@ -415,15 +419,15 @@ $app = $sp->app_info('APPID'); ```json { - "data": + "data": { - "id": "UXOSIYrdtL4cSGp3", - "name": "www2", - "autoupdates": true, - "firewall": true, - "lastaddress": "1.2.3.4", - "lastconn": 1403130554, - "datecreated": 1403130553 + "id": "UXOSIYrdtL4cSGp3", + "name": "www2", + "autoupdates": true, + "firewall": true, + "lastaddress": "1.2.3.4", + "lastconn": 1403130554, + "datecreated": 1403130553 } } ``` @@ -450,18 +454,18 @@ When the request goes through successfully you should get this returned: ```json { - "actionid": "dIrCNoWunW92lPjw", - "data": - { - "id": "nlcN0TwdZAyNEgdp", - "datecreated": 1403143012, - "name": "gallery", - "sysuserid": "RvnwAIfuENyjUVnl", - "domains": ["www.example.com", "example.com"], - "ssl": null, - "serverid": "4zGDDO2xg30yEeum", - "runtime": "php7.0" - } + "actionid": "dIrCNoWunW92lPjw", + "data": + { + "id": "nlcN0TwdZAyNEgdp", + "datecreated": 1403143012, + "name": "gallery", + "sysuserid": "RvnwAIfuENyjUVnl", + "domains": ["www.example.com", "example.com"], + "ssl": null, + "serverid": "4zGDDO2xg30yEeum", + "runtime": "php7.0" + } } ``` @@ -482,18 +486,18 @@ $response = $sp->app_update('APPID', 'RUNTIME', 'DOMAINS'); ```json { - "actionid": "KlsNzLikw3BRvShc", - "data": - { - "id": "nlcN0TwdZAyNEgdp", - "datecreated": 1403143012, - "name": "gallery", - "sysuserid": "RvnwAIfuENyjUVnl", - "domains": ["www.example.com", "example.com"], - "ssl": null, - "serverid": "4zGDDO2xg30yEeum", - "runtime": "php5.6" - } + "actionid": "KlsNzLikw3BRvShc", + "data": + { + "id": "nlcN0TwdZAyNEgdp", + "datecreated": 1403143012, + "name": "gallery", + "sysuserid": "RvnwAIfuENyjUVnl", + "domains": ["www.example.com", "example.com"], + "ssl": null, + "serverid": "4zGDDO2xg30yEeum", + "runtime": "php5.6" + } } ``` @@ -505,8 +509,8 @@ $response = $sp->app_delete('APPID'); ```json { - "actionid": "88Ypexhx28Y63eyA", - "data": {} + "actionid": "88Ypexhx28Y63eyA", + "data": {} } ``` @@ -522,19 +526,19 @@ $databases = $sp->database_list(); ```json { - "data": - [ - { - "id": "hdXkAZchuj27Hm1L", - "name": "wordpress", - "appid": "c77JD4gZooGjrF8K", - "serverid": "4zGDDO2xg30yEeum", - "user": { - "id": "vt08Qz9kjOC3RVLr", - "name": "robert" - } - } - ] + "data": + [ + { + "id": "hdXkAZchuj27Hm1L", + "name": "wordpress", + "appid": "c77JD4gZooGjrF8K", + "serverid": "4zGDDO2xg30yEeum", + "user": { + "id": "vt08Qz9kjOC3RVLr", + "name": "robert" + } + } + ] } ``` @@ -547,16 +551,16 @@ $app = $sp->database_info('DBID'); ```json { - "data": - { - "id": "8PV1OIAlAW3jbGmM", - "name": "gallerydb", - "appid": "nlcN0TwdZAyNEgdp", - "serverid": "4zGDDO2xg30yEeum", - "user": { - "id": "k2HWtU33mpUsfOdA", - "name": "arturo" - } + "data": + { + "id": "8PV1OIAlAW3jbGmM", + "name": "gallerydb", + "appid": "nlcN0TwdZAyNEgdp", + "serverid": "4zGDDO2xg30yEeum", + "user": { + "id": "k2HWtU33mpUsfOdA", + "name": "arturo" + } } } ``` @@ -582,17 +586,17 @@ When the request goes through successfully you should get this returned: ```json { - "actionid": "gPFiWP9hFNUxvT70", + "actionid": "gPFiWP9hFNUxvT70", "data": { - "id": "8PV1OIAlAW3jbGmM", - "name": "gallerydb", - "appid": "nlcN0TwdZAyNEgdp", - "serverid": "4zGDDO2xg30yEeum", - "user": { - "id": "k2HWtU33mpUsfOdA", - "name": "arturo" - } + "id": "8PV1OIAlAW3jbGmM", + "name": "gallerydb", + "appid": "nlcN0TwdZAyNEgdp", + "serverid": "4zGDDO2xg30yEeum", + "user": { + "id": "k2HWtU33mpUsfOdA", + "name": "arturo" + } } } ``` @@ -615,17 +619,17 @@ $response = $sp->database_update('DBID', 'USERID', 'PASSWORD'); ```json { - "actionid": "VfH12ukDJFv0RZAO", + "actionid": "VfH12ukDJFv0RZAO", "data": { - "id": "8PV1OIAlAW3jbGmM", - "name": "gallerydb", - "appid": "nlcN0TwdZAyNEgdp", - "serverid": "4zGDDO2xg30yEeum", - "user": { - "id": "k2HWtU33mpUsfOdA", - "name": "arturo" - } + "id": "8PV1OIAlAW3jbGmM", + "name": "gallerydb", + "appid": "nlcN0TwdZAyNEgdp", + "serverid": "4zGDDO2xg30yEeum", + "user": { + "id": "k2HWtU33mpUsfOdA", + "name": "arturo" + } } } ``` @@ -638,8 +642,8 @@ $response = $sp->database_delete('APPID'); ```json { - "actionid": "88Ypexhx28Y63eyA", - "data": {} + "actionid": "88Ypexhx28Y63eyA", + "data": {} } ``` @@ -664,12 +668,12 @@ $ssl = $sp->ssl_add('APPID', 'KEY', 'CERT', 'CACERTS); ```json { - "actionid": "BzcMNZ9sdBY62vTd", + "actionid": "BzcMNZ9sdBY62vTd", "data": { - "key": "-----BEGIN PRIVATE KEY----- ... -----END PRIVATE KEY-----", - "cert": "-----BEGIN CERTIFICATE----- ... -----END CERTIFICATE-----", - "cacerts": "-----BEGIN CERTIFICATE----- ... -----END CERTIFICATE-----" + "key": "-----BEGIN PRIVATE KEY----- ... -----END PRIVATE KEY-----", + "cert": "-----BEGIN CERTIFICATE----- ... -----END CERTIFICATE-----", + "cacerts": "-----BEGIN CERTIFICATE----- ... -----END CERTIFICATE-----" } } ``` diff --git a/lib/ServerPilot.php b/lib/ServerPilot.php index 11f555e..a094cd2 100644 --- a/lib/ServerPilot.php +++ b/lib/ServerPilot.php @@ -395,7 +395,7 @@ private function _send_request( $url_segs, $params = array(), $http_method = 'ge curl_close( $req ); // Everything when fine - if($http_status == 200) + if( $http_status == 200 ) { // Decode JSON by default if( $this->decode ) @@ -408,11 +408,11 @@ private function _send_request( $url_segs, $params = array(), $http_method = 'ge $data = json_decode( $response ); // The error was provided by serverpilot - if(property_exists($response, 'error')) + if( property_exists( $response, 'error' ) ) throw new ServerPilotException($data->error, $http_status); // No error as provided, pick a default - switch($http_status) + switch( $http_status ) { case 400: throw new ServerPilotException('We couldn\'t understand your request. Typically missing a parameter or header.', $http_status);