Merge pull request #10 from phansys/composer

[Upgrade] Move to NSs, autoloading with PSR-4 and dependency management

Author: underscorephil

README.textile

@@ -4,9 +4,9 @@ h2. 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 SoftLayer_XmlrpcClient classes is done in the following steps:
+Making API calls using the \SoftLayer\SoapClient or \SoftLayer\XmlRpcClient classes is done in the following steps:
 
-# Instantiate a new SoftLayer_SoapClient or SoftLayer_XmlrpcClient object using the SoftLayer_SoapClient::getClient() or SoftLayer_XmlrpcClient::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 SoftLayer_SoapClient::API_PRIVATE_ENDPOINT or SoftLayer_XmlrpcClient::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.
+# Instantiate a new \SoftLayer\SoapClient or \SoftLayer\XmlRpcClient object using the \SoftLayer\SoapClient::getClient() or \SoftLayer\XmlRpcClient::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 \SoftLayer\SoapClient::API_PRIVATE_ENDPOINT or \SoftLayer\XmlRpcClient::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.
 # Define and add optional headers to the client, such as object masks and result limits.
 # 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.
 
@@ -16,36 +16,39 @@ The most up to date version of this library can be found on the SoftLayer github
 
 h2. System Requirements
 
-The SoftLayer_SoapClient class requires at least PHP 5.2.3 and the PHP SOAP enxtension installed. The SoftLayer_Xmlrpc class requires PHP at least PHP 5 and the PHP XML-RPC extension installed.
+The \SoftLayer\SoapClient class requires at least PHP 5.3.0 and the PHP SOAP enxtension installed. The \SoftLayer\XmlRpcClient class requires PHP at least PHP 5 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.
 
 h2. 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.
+Install the SoftLayer API client using "Composer":https://getcomposer.org/.
+<pre><code>
+composer require softlayer/softlayer-api-php-client:~1.0@dev
+</code></pre>
 
 h2. Usage
 
-These examples use the SoftLayer_SoapClient class. If you wish to use the XML-RPC API then replace mentions of SoapClient.class.php with XmlrpcClient.class.php and SoftLayer_SoapClient with SoftLayer_XmlrpcClient.
+These examples use the \SoftLayer\SoapClient class. If you wish to use the XML-RPC API then replace mentions of SoapClient.class.php with XmlrpcClient.class.php and \SoftLayer\SoapClient with \SoftLayer\XmlRpcClient.
 
 Here's a simple usage example that retrieves account information by calling the "getObject()":http://sldn.softlayer.com/reference/services/SoftLayer_Account/getObject method in the "SoftLayer_Account":http://sldn.softlayer.com/reference/services/SoftLayer_Account service:
 
 <pre><code>
 <?php
 
-require_once dirname(__FILE__) . '/SoftLayer/SoapClient.class.php';
+require_once __DIR__.'/vendor/autoload.php';
 
 $apiUsername = 'set me';
 $apiKey = 'set me too';
 
 // Initialize an API client for the SoftLayer_Account service.
-$client = SoftLayer_SoapClient::getClient('SoftLayer_Account', null, $apiUsername, $apiKey);
+$client = \SoftLayer\SoapClient::getClient('SoftLayer_Account', null, $apiUsername, $apiKey);
 
 // Retrieve our account record
 try {
     $account = $client->getObject();
     print_r($account);
-} catch (Exception $e) {
+} catch (\Exception $e) {
     die('Unable to retrieve account information: ' . $e->getMessage());
 }
 </code></pre>
@@ -55,16 +58,16 @@ For a more complex example we'll retrieve a support ticket with id 123456 along
 <pre><code>
 <?php
 
-require_once dirname(__FILE__) . '/SoftLayer/SoapClient.class.php';
+require_once __DIR__.'/vendor/autoload.php';
 
 $apiUsername = 'set me';
 $apiKey = 'set me too';
 
 // Initialize an API client for ticket 123456
-$client = SoftLayer_SoapClient::getClient('SoftLayer_Ticket', 123456, $apiUsername, $apiKey);
+$client = \SoftLayer\SoapClient::getClient('SoftLayer_Ticket', 123456, $apiUsername, $apiKey);
 
 // Create an object mask and assign it to our API client.
-$objectMask = new SoftLayer_ObjectMask();
+$objectMask = new \SoftLayer\ObjectMask();
 $objectMask->updates;
 $objectMask->assignedUser;
 $objectMask->attachedHardware->datacenter;
@@ -73,18 +76,18 @@ $client->setObjectMask($objectMask);
 // Retrieve the ticket record
 try {
     $ticket = $client->getObject();
-} catch (Exception $e) {
+} catch (\Exception $e) {
     die('Unable to retrieve ticket record: ' . $e->getMessage());
 }
 
 // Update the ticket
-$update = new stdClass();
+$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) {
+} catch (\Exception $e) {
     die('Unable to update ticket: ' . $e->getMessage());
 }
 </code></pre>

composer.json

@@ -0,0 +1,28 @@
+{
+    "name": "softlayer/softlayer-api-php-client",
+    "description": "SoftLayer API PHP client",
+    "keywords": ["softlayer"],
+    "homepage": "http://sldn.softlayer.com/article/PHP",
+    "license": "MIT",
+    "authors": [
+        {
+            "name": "SoftLayer Development Team",
+            "email": "[email protected]"
+        }
+    ],
+    "require": {
+        "php": ">=5.3",
+        "ext-xmlrpc": "*",
+        "ext-soap": "*"
+    },
+    "autoload": {
+        "psr-4": {
+            "SoftLayer\\": "src/"
+        }
+    },
+    "extra": {
+        "branch-alias": {
+            "dev-master": "1.0-dev"
+        }
+    }
+}

composer.lock

@@ -27,16 +27,42 @@
  * POSSIBILITY OF SUCH DAMAGE.
  */
 
+use SoftLayer\Common\ObjectMask;
+use SoftLayer\SoapClient;
+use SoftLayer\XmlRpcClient;
+
 /**
- * Start by including the API client class. This example assumes that the
- * SoftLayer API classes are in the directory "SoftLayer" relative to this
- * script's path.
+ * Start by including the autoload class.
  *
  * If you wish to use the XML-RPC API then replace mentions of
- * SoapClient.class.php with XmlrpcClient.class.php and SoftLayer_SoapClient
- * with SoftLayer_XmlrpcClient.
+ * SoapClient with XmlRpcClient.
  */
-require_once dirname(__FILE__) . '/SoftLayer/SoapClient.class.php';
+$files = [
+    __DIR__.'/vendor/autoload.php',
+    __DIR__.'/../../autoload.php',
+];
+
+$autoload = false;
+foreach ($files as $file) {
+    if (is_file($file)) {
+        $autoload = include_once $file;
+
+        break;
+    }
+}
+
+if (!$autoload) {
+    die(<<<MSG
+Unable to find autoload.php file, please use composer to load dependencies:
+
+wget http://getcomposer.org/composer.phar
+php composer.phar install
+
+Visit http://getcomposer.org/ for more information.
+
+MSG
+);
+}
 
 /**
  * It's possible to define your SoftLayer API username and key diredtly in the
@@ -48,7 +74,7 @@
 
 /**
  * Usage:
- * SoftLayer_SoapClient::getClient([API Service], <object id>, [username], [API key]);
+ * SoapClient::getClient([API Service], <object id>, [username], [API key]);
  *
  * API Service: The name of the API service you wish to connect to.
  * id:          An optional id to initialize your API service with, if you're
@@ -57,7 +83,7 @@
  * username:    Your SoftLayer API username.
  * API key:     Your SoftLayer API key,
  */
-$client = SoftLayer_SoapClient::getClient('SoftLayer_Account', null, $apiUsername, $apiKey);
+$client = SoapClient::getClient('SoftLayer_Account', null, $apiUsername, $apiKey);
 
 /**
  * Once your client object is created you can call API methods for that service
@@ -71,7 +97,7 @@
  */
 try {
     print_r($client->getObject());
-} catch (Exception $e) {
+} catch (\Exception $e) {
     die($e->getMessage());
 }
 
@@ -84,10 +110,10 @@
  */
 
 // Declare an API client to connect to the SoftLayer_Ticket API service.
-$client = SoftLayer_SoapClient::getClient('SoftLayer_Ticket', 123456, $apiUsername, $apiKey);
+$client = SoapClient::getClient('SoftLayer_Ticket', 123456, $apiUsername, $apiKey);
 
 // Assign an object mask to our API client:
-$objectMask = new SoftLayer_ObjectMask();
+$objectMask = new ObjectMask();
 $objectMask->updates;
 $objectMask->assignedUser;
 $objectMask->attachedHardware->datacenter;
@@ -97,17 +123,17 @@
 try {
     $ticket = $client->getObject();
     print_r($ticket);
-} catch (Exception $e) {
+} catch (\Exception $e) {
     die('Unable to retrieve ticket record: ' . $e->getMessage());
 }
 
 // Now update the ticket.
-$update = new stdClass();
+$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) {
+} catch (\Exception $e) {
     die('Unable to update ticket: ' . $e->getMessage());
 }

example.php

@@ -27,12 +27,14 @@
  * POSSIBILITY OF SUCH DAMAGE.
  */
 
+namespace SoftLayer\Common;
+
 /**
  * A simple object mask implementation.
  *
- * Use this class instead of stdClass when defining object masks in SoftLayer
+ * Use this class instead of \stdClass when defining object masks in SoftLayer
  * API calls. This one is a bit easier to use. For example, to declare a new
- * object mask using stdClass enter:
+ * object mask using \stdClass enter:
  *
  * $objectMask = new StdClass();
  * $objectMask->datacenter = new StdClass();
@@ -41,16 +43,16 @@
  * $objectMask->softwareComponents = new StdClass();
  * $objectMask->softwareComponents->passwords = new StdClass();
  *
- * Building an object mask using SoftLayer_ObjectMask is a bit easier to
+ * Building an object mask using ObjectMask is a bit easier to
  * type:
  *
- * $objectMask = new SoftLayer_ObjectMask();
+ * $objectMask = new ObjectMask();
  * $objectMask->datacenter;
  * $objectMask->serverRoom;
  * $objectMask->provisionDate;
  * $objectMask->sofwareComponents->passwords;
  *
- * Use SoftLayer_SoapClient::setObjectMask() to set these object masks before
+ * Use SoapClient::setObjectMask() to set these object masks before
  * making your SoftLayer API calls.
  *
  * For more on object mask usage in the SoftLayer API please see
@@ -65,10 +67,10 @@
  * @author      SoftLayer Technologies, Inc. <[email protected]>
  * @copyright   Copyright (c) 2009 - 2010, Softlayer Technologies, Inc
  * @license     http://sldn.softlayer.com/article/License
- * @see         SoftLayer_SoapClient::setObjectMask()
- * @see         SoftLayer_XmlrpcClient::setObjectMask()
+ * @see         SoapClient::setObjectMask()
+ * @see         XmlRpcClient::setObjectMask()
  */
-class SoftLayer_ObjectMask
+class ObjectMask
 {
     /**
      * Define an object mask value
@@ -77,7 +79,7 @@ class SoftLayer_ObjectMask
      */
     public function __get($var)
     {
-        $this->{$var} = new SoftLayer_ObjectMask();
+        $this->{$var} = new self();
 
         return $this->{$var};
     }