Adding doc for caching credentials

Author: jamiehannaford

composer.json

@@ -25,7 +25,7 @@
         "guzzle/http" : "3.8.*@dev"
     },
     "require-dev" : {
-        "guzzle/guzzle": "3.8.*@dev",
+        "guzzle/guzzle": "dev-master",
         "psr/log": "1.0.*",
         "satooshi/php-coveralls": "0.6.*@dev"
     }

docs/userguide/caching-credentials.md

@@ -0,0 +1,39 @@
+# 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.
+
+```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.

lib/OpenCloud/Common/PersistentObject.php

@@ -334,7 +334,7 @@ public function getUrl($path = null, array $query = array())
             $url = Url::factory($url);
         }
 
-        return $url->addPath($path)->setQuery($query);
+        return $url->addPath((string) $path)->setQuery($query);
     }
 
     /**

lib/OpenCloud/Identity/Resource/Token.php

@@ -66,7 +66,7 @@ public function getExpires()
      */
     public function hasExpired()
     {
-        return time() >= $this->expires;
+        return time() >= strtotime($this->expires);
     }
 
 }

lib/OpenCloud/ObjectStore/Resource/AbstractContainer.php

@@ -70,7 +70,8 @@ public function getUrl($path = null, array $params = array())
         }
 
         $url = $this->getService()->getUrl();
-        return $url->addPath((string) $this->getName())->addPath($path)->setQuery($params);
+
+        return $url->addPath((string) $this->getName())->addPath((string) $path)->setQuery($params);
     }
 
     protected function createRefreshRequest()