June 20, 2011


PHP

SoftLayer provides a PHP-based API client that takes the heavy lifting out making manual SOAP or XML-RPC calls.

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:

  • PHP 5.2.3 or higher
  • One of the following PHP extensions:

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

Making SOAP Calls

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:

  • The name of the service you wish to call.
  • An optional id number of the specific object you wish to work with. Pass a 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.
  • Your API username.
  • Your API key.

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;

Using XML-RPC

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:

  • Include XmlrpcClient.class.php instead of SoapClient.class.php
  • Create an API client with SoftLayer_XmlrpcClient::getClient() instead of SoftLayer_SoapClient::getClient()
    For instance:

require_once('/path/to/SoftLayer/XmlrpcClient.class.php');
 
$apiUsername = 'set me';
$apiKey = 'set me';
 
$client = SoftLayer_XmlrpcClient::getClient('SoftLayer_Account' null, $apiUsername, $apiKey);

Using Object Masks

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:

  • The account's physical hardware
  • The hardware's operating system record
  • Operating system password
  • Network components
  • The datacenter in which the hardware is located
  • The number of processors in each hardware

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();

Using Result Limits

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:

  • The number of results to limit your call.
  • An optional offset to begin your result set.
    The example below incorporates the required information to set a result limit:

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();

Error Handling

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());
}

Referenced API Components

Services

Data Types

Methods