SoftLayer provides a PHP-based API client that takes the heavy lifting out making manual SOAP or XML-RPC calls. To use the PHP-based API client, the following system requirements must be met:
Download the SoftLayer PHP API client from its project page on SoftLayer's github profile. Once downloaded, extract the PHP API Client to a directory local to your PHP project or into your PHP installation's include_path.
Download the SoftLayer API PHP client
Once the API client is downloaded and installed the first thing to do is include the SoapClient.class.php file in your script. This file defines SoftLayer's client objects.
require_once('/path/to/SoftLayer/SoapClient.class.php');Next, create a client object for the SoftLayer API service you wish to use. SoftLayer_SoapClient::getClient() will take care of this for you and takes four parameters:
null value if you're either working with the SoftLayer_Account service or are not working with a specific server, support ticket, invoice, or other object. This id creates an initialization parameter in your API call.The code snippet below provides an example of making a SOAP call, utilizing the parameters outlined above:
require_once('/path/to/SoftLayer/SoapClient.class.php');
$apiUsername = 'set me';
$apiKey = 'set me';
/**
* Create a client to the SoftLayer_Account API service.
*/
$client = SoftLayer_SoapClient::getClient('SoftLayer_Account', null, $apiUsername, $apiKey);
/**
* Work directly with the SoftLayer_Hardware_Server record with the hardware id
* 1234.
*/
$serverId = 1234;
$client = SoftLayer_SoapClient::getClient('SoftLayer_Hardware_Server', $serverId, $apiUsername, $apiKey);Once your API client object is ready call a SoftLayer API method as if it were local to your client object. Assign the result of your API call to a variable to get the call's result. Complex type objects are returned as PHP stdClass objects. Likewise, use stdClass objects if you need to pass complex type parameters to your API calls. For example:
require_once('/path/to/SoftLayer/SoapClient.class.php');
$apiUsername = 'set me';
$apiKey = 'set me';
$domainId = 1234;
$client = SoftLayer_SoapClient::getClient('SoftLayer_Dns_Domain', $domainId, $apiUsername, $apiKey);
/**
* Create a new A record in a domain.
*/
$newRecord = $client->createARecord('myhost', '127.0.0.1', 86400);
echo 'New A record id: ' . $newRecord->id;
/**
* Create a new domain record.
*
* This requires an API client with a null id, and use a stdClass object to model
*our new domain.
*/
$client = SoftLayer_SoapClient::getClient('SoftLayer_Dns_Domain', null, $apiUsername, $apiKey);
$domain = new stdClass();
$domain->name = 'example.org';
$domain->resourceRecords = array();
$domain->resourceRecords[0] = new stdClass();
$domain->resourceRecords[0]->host = '@';
$domain->resourceRecords[0]->data = '127.0.0.1';
$domain->resourceRecords[0]->type = 'a';
$newDomain = $client->createObject($domain);
echo 'New domain id: ' . $newDomain->id;The SoftLayer API PHP client supports both the SOAP and XML-RPC protocols interchangeably. If you wish to use XML-RPC instead of SOAP, two changes are required:
XmlrpcClient.class.php instead of SoapClient.class.phpSoftLayer_XmlrpcClient::getClient() instead of SoftLayer_SoapClient::getClient()
require_once('/path/to/SoftLayer/XmlrpcClient.class.php');
$apiUsername = 'set me';
$apiKey = 'set me';
$client = SoftLayer_XmlrpcClient::getClient('SoftLayer_Account' null, $apiUsername, $apiKey);Create an object mask in your API call by first declaring a new SoftLayer_ObjectMask object. Define the relational properties you wish to retrieve as local properties in your new mask object. Finally, bind it to your API client by using the setObjectMask() method. This example retrieves the following information:
require_once('/path/to/SoftLayer/SoapClient.class.php');
$apiUsername = 'set me';
$apiKey = 'set me';
$client = SoftLayer_SoapClient::getClient('SoftLayer_Account', null, $apiUsername, $apiKey);
/**
* Retrieve items related to hardware.
*
* Operating system, operating system passwords, all network components, the
* datacenter the server is located in, and the number of processors in each
* server.
*/
$objectMask = new SoftLayer_ObjectMask();
$objectMask->hardware->operatingSystem->passwords;
$objectMask->hardware->networkComponents;
$objectMask->hardware->datacenter;
$objectMask->hardware->processorCount;
$client->setObjectMask($objectMask);
$hardware = $client->getHardware();When calling data, especially queries that involve pulling snippets of information from larger groups, utilizing result limits will greatly decrease your wait time for the return.
Limit the number of results in your API call with your client object's setResultLimit() method. This method takes two parameters:
require_once('/path/to/SoftLayer/SoapClient.class.php');
$apiUsername = 'set me';
$apiKey = 'set me';
$client = SoftLayer_SoapClient::getClient('SoftLayer_Account', null, $apiUsername, $apiKey);
/**
* Retrieve our first two open support tickets.
*/
$client->setResultLimit(2);
$tickets = $client->getOpenTickets();SoftLayer API call errors are thrown by the PHP client as exceptions. Place calls to the SoftLayer API inside try/catch blocks to ensure proper handling. Use the PHP exception classes' getMessage() method to access errors returned by the SoftLayer API. The following script contains an example of such error:
require_once('/path/to/SoftLayer/SoapClient.class.php');
$apiUsername = 'set me!';
$apiKey = 'an incorrect API key';
$client = new SoftLayer_SoapClient('SoftLayer_Account', null, $apiUsername, $apiKey);
/**
* Exit the script with the message:
* "Unable to retrieve account information: Invalid API key"
*/
try {
$account = $client->getObject();
} catch (Exception $e) {
die('Unable to retrieve account information: ' . $e->getMessage());
}