Attempt to fix 5.3 segfault

Author: Jamie Hannaford

doc/_build/doctrees/auth.doctree

@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: da7e999e4172075fe9536fec2c0e5662
+tags: 645f666f9bcd5a90fca523b33c5a78b7

doc/_build/doctrees/caching-creds.doctree

@@ -0,0 +1,54 @@
+Authentication
+==============
+
+The client does not automatically authenticate against the API when it is
+instantiated - it waits for an API call. When this happens, it checks
+whether the current “token” has expired, and (re-)authenticates if
+necessary.
+
+You can force authentication, by calling:
+
+.. code-block:: php
+
+  $client->authenticate();
+
+If the credentials are incorrect, a ``401`` error will be returned. If
+credentials are correct, a ``200`` status is returned with your Service
+Catalog.
+
+
+Service Catalog
+---------------
+
+The Service Catalog is returned on successful authentication, and is
+composed of all the different API services available to the current
+tenant. All of this functionality is encapsulated in the ``Catalog``
+object, which allows you greater control and interactivity.
+
+.. code-block:: php
+
+  /** @var OpenCloud\Common\Service\Catalog */
+  $catalog = $client->getCatalog();
+
+  // Return a list of OpenCloud\Common\Service\CatalogItem objects
+  foreach ($catalog->getItems() as $catalogItem) {
+
+      $name = $catalogItem->getName();
+      $type = $catalogItem->getType();
+
+      if ($name == 'cloudServersOpenStack' && $type == 'compute') {
+          break;
+      }
+
+      // Array of OpenCloud\Common\Service\Endpoint objects
+      $endpoints = $catalogItem->getEndpoints();
+      foreach ($endpoints as $endpoint) {
+          if ($endpoint->getRegion() == 'DFW') {
+              echo $endpoint->getPublicUrl();
+          }
+      }
+  }
+
+As you can see, you have access to each Service’s name, type and list of
+endpoints. Each endpoint provides access to the specific region, along
+with its public and private endpoint URLs.

doc/_build/doctrees/customizing-clients.doctree

@@ -0,0 +1,44 @@
+Caching credentials
+===================
+
+You can speed up your API operations by caching your credentials in a
+(semi-)permanent location, such as your DB or local filesystem. This
+enable subsequent requests to access a shared resource, instead of
+repetitively having to re-authenticate on every thread of execution.
+
+Tokens are valid for 24 hours, so you can effectively re-use the same
+cached value for that period. If you try to use a cached version that
+has expired, an authentication request will be made.
+
+Filesystem example
+------------------
+
+In this example, credentials will be saved to a file in the local
+filesystem. Be sure to exclude it from your VCS.
+
+.. code-block:: php
+
+  use OpenCloud\Rackspace;
+
+  $client = new Rackspace(Rackspace::US_IDENTITY_ENDPOINT, array(
+      'username' => 'foo',
+      'apiKey'   => 'bar'
+  ));
+
+  $cacheFile = __DIR__ . '/.opencloud_token';
+
+  // If the cache file exists, try importing it into the client
+  if (file_exists($cacheFile)) {
+      $data = unserialize(file_get_contents($cacheFile));
+      $client->importCredentials($data);
+  }
+
+  $token = $client->getTokenObject();
+
+  // If no token exists, or the current token is expired, re-authenticate and save the new token to disk
+  if (!$token || ($token && $token->hasExpired())) {
+      $client->authenticate();
+      file_put_contents($cacheFile, serialize($client->exportCredentials()));
+  }
+
+In tests, the above code shaved about 1-2s off the execution time.

doc/_build/doctrees/debugging.doctree

@@ -0,0 +1,144 @@
+Customizing Clients
+===================
+
+Logger injection
+----------------
+
+As the ``Rackspace`` client extends the ``OpenStack`` client, they both support
+passing ``$options`` as an array via the constructor's third parameter. The
+options are passed as a config to the `Guzzle` client, but also allow to inject
+your own logger.
+
+Your logger should implement the ``Psr\Log\LoggerInterface`` `as defined in
+PSR-3 <https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-3-logger-interface.md>`_.
+One example of a compatible logger is `Monolog <https://github.com/Seldaek/monolog>`_.
+When the client does create a service, it will inject the logger if one is
+available.
+
+To inject a ``LoggerInterface`` compatible logger into a new client:
+
+.. code-block:: php
+
+  use Monolog\Logger;
+  use OpenCloud\OpenStack;
+
+  // create a log channel
+  $logger = new Logger('name');
+
+  $client = new OpenStack('http://identity.my-openstack.com/v2.0', array(
+    'username' => 'foo',
+    'password' => 'bar'
+  ), array(
+    'logger' => $logger,
+  ));
+
+
+Authentication
+--------------
+
+The client does not automatically authenticate against the API when it is
+instantiated - it waits for an API call. When this happens, it checks
+whether the current “token” has expired, and (re-)authenticates if
+necessary.
+
+You can force authentication, by calling:
+
+.. code-block:: php
+
+  $client->authenticate();
+
+If the credentials are incorrect, a ``401`` error will be returned. If
+credentials are correct, a ``200`` status is returned with your Service
+Catalog.
+
+
+Service Catalog
+---------------
+
+The Service Catalog is returned on successful authentication, and is
+composed of all the different API services available to the current
+tenant. All of this functionality is encapsulated in the ``Catalog``
+object, which allows you greater control and interactivity.
+
+.. code-block:: php
+
+  /** @var OpenCloud\Common\Service\Catalog */
+  $catalog = $client->getCatalog();
+
+  // Return a list of OpenCloud\Common\Service\CatalogItem objects
+  foreach ($catalog->getItems() as $catalogItem) {
+
+      $name = $catalogItem->getName();
+      $type = $catalogItem->getType();
+
+      if ($name == 'cloudServersOpenStack' && $type == 'compute') {
+          break;
+      }
+
+      // Array of OpenCloud\Common\Service\Endpoint objects
+      $endpoints = $catalogItem->getEndpoints();
+      foreach ($endpoints as $endpoint) {
+          if ($endpoint->getRegion() == 'DFW') {
+              echo $endpoint->getPublicUrl();
+          }
+      }
+  }
+
+As you can see, you have access to each Service’s name, type and list of
+endpoints. Each endpoint provides access to the specific region, along
+with its public and private endpoint URLs.
+
+
+Default HTTP headers
+--------------------
+
+To set default HTTP headers:
+
+.. code-block:: php
+
+  $client->setDefaultOption('headers/X-Custom-Header', 'FooBar');
+
+
+User agents
+-----------
+
+php-opencloud will send a default ``User-Agent`` header for every HTTP
+request, unless a custom value is provided by the end-user. The default
+header will be in this format:
+
+  User-Agent: OpenCloud/xxx cURL/yyy PHP/zzz
+
+where ``xxx`` is the current version of the SDK, ``yyy`` is the current
+version of cURL, and ``zzz`` is the current PHP version. To override
+this default, you must run:
+
+.. code-block:: php
+
+  $client->setUserAgent('MyCustomUserAgent');
+
+which will result in:
+
+  User-Agent: MyCustomUserAgent
+
+If you want to set a *prefix* for the user agent, but retain the default
+``User-Agent`` as a suffix, you must run:
+
+.. code-block:: php
+
+  $client->setUserAgent('MyPrefix', true);
+
+which will result in:
+
+  User-Agent: MyPrefix OpenCloud/xxx cURL/yyy PHP/zzz
+
+where ``$client`` is an instance of ``OpenCloud\OpenStack`` or
+``OpenCloud\Rackspace``.
+
+
+Other functionality
+-------------------
+
+For a full list of functionality provided by Guzzle, please consult the
+`official documentation`_.
+
+.. _official documentation: http://docs.guzzlephp.org/en/latest/http-client/client.html

doc/_build/doctrees/environment.pickle

@@ -0,0 +1,103 @@
+Debugging
+=========
+
+There are two important debugging strategies to use when encountering
+problems with HTTP transactions.
+
+Strategy 1: Meaningful exception handling
+-----------------------------------------
+
+If the API returns a ``4xx`` or ``5xx`` status code, it indicates that
+there was an error with the sent request, meaning that the transaction
+cannot be adequately completed.
+
+The Guzzle HTTP component, which forms the basis of our SDK's transport
+layer, utilizes `numerous exception
+classes <https://github.com/guzzle/guzzle/tree/master/src/Guzzle/Http/Exception>`__
+to handle this error logic.
+
+The two most common exception classes are:
+
+-  ``Guzzle\Http\Exception\ClientErrorResponseException``, which is
+   thrown when a ``4xx`` response occurs
+
+-  ``Guzzle\Http\Exception\ServerErrorResponseException``, which is
+   thrown when a ``5xx`` response occurs
+
+Both of these classes extend the base ``BadResponseException`` class.
+
+This provides you with the granularity you need to debug and handle
+exceptions.
+
+An example with Swift
+~~~~~~~~~~~~~~~~~~~~~
+
+If you're trying to retrieve a Swift resource, such as a Data Object,
+and you're not completely certain that it exists, it makes sense to wrap
+your call in a try/catch block:
+
+.. code-block:: php
+
+  use Guzzle\Http\Exception\ClientErrorResponseException;
+
+  try {
+      return $service->getObject('foo.jpg');
+  } catch (ClientErrorResponseException $e) {
+      if ($e->getResponse()->getStatusCode() == 404) {
+        // Okay, the resource does not exist
+        return false;
+      }
+  } catch (\Exception $e) {
+      // Some other exception was thrown...
+  }
+
+
+Both ``ClientErrorResponseException`` and
+``ServerErrorResponseException`` have two methods that allow you to
+access the HTTP transaction:
+
+.. code-block:: php
+
+  // Find out the faulty request
+  $request = $e->getRequest();
+
+  // Display everything by casting as string
+  echo (string) $request;
+
+  // Find out the HTTP response
+  $response = $e->getResponse();
+
+  // Output that too
+  echo (string) $response;
+
+
+Strategy 2: Wire logging
+------------------------
+
+Guzzle provides a `Log
+plugin <http://docs.guzzlephp.org/en/latest/plugins/log-plugin.html>`__
+that allows you to log everything over the wire, which is useful if you
+don't know what's going on.
+
+Here's how you enable it:
+
+Install the plugin
+~~~~~~~~~~~~~~~~~~
+
+.. code-block:: bash
+
+  composer require guzzle/guzzle
+
+
+Add to your client
+~~~~~~~~~~~~~~~~~~
+
+.. code-block:: php
+
+  use Guzzle\Plugin\Log\LogPlugin;
+
+  $client->addSubscriber(LogPlugin::getDebugPlugin());
+
+
+The above will add a generic logging subscriber to your client, which
+will output every HTTP transaction to `STDOUT`.