A SoftLayer API PHP client.

Overview

The SoftLayer API PHP client classes provide a simple method for connecting to and making calls from the SoftLayer API and provides support for many of the SoftLayer API’s features. Method calls and client management are handled by the PHP SOAP and XML-RPC extensions.

Making API calls using the SoftLayer_SoapClient or SLXmlrpcClient classes is done in the following steps:

1. Instantiate a new SLSoapClient or SLXmlrpcClient object using the SLSoapClient::getClient() or SLXmlrpcClient::getClient() methods. Provide the name of the service that you wish to query, an optional id number of the object that you wish to instantiate, your SoftLayer API username, your SoftLayer API key, and an optional API endpoint base URL. The client classes default to connect over the public Internet. Enter SLSoapClient::API_PRIVATE_ENDPOINT or SLXmlrpcClient::API_PRIVATE_ENDPOINT to connect to the API over SoftLayer’s private network. The system making API calls must be connected to SoftLayer’s private network (eg. purchased from SoftLayer or connected via VPN) in order to use the private network API endpoints.
2. Define and add optional headers to the client, such as object masks and result limits.
3. Call the API method you wish to call as if it were local to your client object. This class throws exceptions if it’s unable to execute a query, so it’s best to place API method calls in try / catch statements for proper error handling.

Once your method is executed you may continue using the same client if you need to connect to the same service or define another client object if you wish to work with multiple services at once.

The most up to date version of this library can be found on the SoftLayer github public repositories: http://github.com/softlayer/ . Please post to the SoftLayer forums <http://forums.softlayer.com/> or open a support ticket in the SoftLayer customer portal if you have any questions regarding use of this library.

System Requirements

The SLSoapClient class requires at least PHP 5.3 and the PHP SOAP extension installed. The SLXmlrpcClient class requires PHP at least PHP 5.3 and the PHP XML-RPC extension installed.

A valid API username and key are required to call the SoftLayer API. A connection to the SoftLayer private network is required to connect to SoftLayer’s private network API endpopints.

Installation

Download and copy the SoftLayer API client to a directory local to your PHP project or a path within your PHP installation’s include_path.

Usage

Add the following to your composer.json…since this is a fork, we’re not using Packagist and you’ll have to include this repo:

"repositories": [
    {
        "type": "git",
        "url": "https://github.com/shift31/softlayer-api-php-client"
    }
],
"require": {
    "php": ">=5.3.0",
    "shift31/softlayer-api-php-client": "dev-master"
},

These examples use the SLSoapClient class. If you wish to use the XML-RPC API then replace mentions of SLSoapClient with SLXmlrpcClient.

Here’s a simple usage example that retrieves account information by calling the getObject method in the SoftLayer_Account service:

<?php

use SoftLayer\SLSoapClient;

$apiUsername = 'set me';
$apiKey = 'set me too';

// Initialize an API client for the SoftLayer_Account service.
$client = SLSoapClient::getClient('SoftLayer_Account', null, $apiUsername, $apiKey);

// Retrieve our account record
try {
    $account = $client->getObject();
    print_r($account);
} catch (Exception $e) {
    die('Unable to retrieve account information: ' . $e->getMessage());
}

For a more complex example we’ll retrieve a support ticket with id 123456 along with the ticket’s updates, the user it’s assigned to, the servers attached to it, and the datacenter those servers are in. We’ll retrieve our extra information using a nested object mask. After we have the ticket we’ll update it with the text ‘Hello!’.

<?php

use SoftLayer\SLSoapClient;
use SoftLayer\Common\ObjectMask;

$apiUsername = 'set me';
$apiKey = 'set me too';

// Initialize an API client for ticket 123456
$client = SLSoapClient::getClient('SoftLayer_Ticket', 123456, $apiUsername, $apiKey);

// Create an object mask and assign it to our API client.
$objectMask = new ObjectMask();
$objectMask->updates;
$objectMask->assignedUser;
$objectMask->attachedHardware->datacenter;
$client->setObjectMask($objectMask);

// Retrieve the ticket record
try {
    $ticket = $client->getObject();
} catch (Exception $e) {
    die('Unable to retrieve ticket record: ' . $e->getMessage());
}

// Update the ticket
$update = new stdClass();
$update->entry = 'Hello!';

try {
    $update = $client->addUpdate($update);
    echo "Updated ticket 123456. The new update's id is " . $update[0]->id . '.');
} catch (Exception $e) {
    die('Unable to update ticket: ' . $e->getMessage());
}

Author

This software is written by the SoftLayer Development Team <[email protected]>.

PHP 5.3 namespaces and composer support by Shift 31 Consulting <[email protected]>.

Copyright

This software is Copyright © 2009 – 2010 SoftLayer Technologies, Inc. See the bundled LICENSE.textile file for more information.