issue rackspace#34 docs update

gecampbell · gecampbell · commit 6064c031ccff · 2013-01-23T09:28:05.000-06:00
diff --git a/README.md b/README.md
@@ -49,9 +49,8 @@ version list:
 
 ### Installation
 
-You can download the latest official release here:
-
-https://github.com/rackspace/php-opencloud/downloads
+GitHub has deprecated its `/downloads` directory. Click on the `ZIP` button
+on this page to download the entire repository as a .ZIP file.
 
 Move the files in the `lib/` directory to a location in your PHP's
 `include_path` or, conversely, set the `include_path` to point to the
diff --git a/RELEASENOTES.md b/RELEASENOTES.md
@@ -15,6 +15,8 @@ RELEASE NOTES
   the previous behavior, this might cause it to break.**
 * Support for Rackspace Cloud Load Balancers
 * Fix to remove requirement for Tenant ID in authentication
+* Added `ExportCredentials()` and `ImportCredentials()` methods to the
+  `OpenStack` class to permit caching of tokens.
 
 ### 11/06/2012 Version 1.2
 * Adds full support for OpenStack Cinder/Rackspace Cloud Block Storage
diff --git a/docs/userguide/authentication.md b/docs/userguide/authentication.md
@@ -11,15 +11,15 @@ It is simple because you only need to have two pieces of information:
 * The credentials required to authenticate
 
 Once you have authenticated, the cloud provider will respond with a
-[service catalog](http://docs.rackspace.com/auth/api/v2.0/auth-client-devguide/content/Sample_Request_Response-d1e64.html) 
+[service catalog](http://docs.rackspace.com/auth/api/v2.0/auth-client-devguide/content/Sample_Request_Response-d1e64.html)
 that contains links to all the
 various provider's services. All you need to do is specify which service
 to use, and the library will take care of finding the appropriate links.
 
 First, however, you need to know if you're using the Rackspace cloud
 or an OpenStack cloud, and include the proper top-level file. These are
 called *Connection* classes, because they establish a connection between an
-authorized user and a specific cloud deployment. They are required for any use of 
+authorized user and a specific cloud deployment. They are required for any use of
 <b>php-opencloud</b>.
 
 ## Authenticating against OpenStack clouds
@@ -42,7 +42,7 @@ Next, create an `OpenStack` object with the proper credentials:
 
 In this example, `$credentials` is an associative array (or "hashed" array). The
 keys are `username` and `password` and their values are your assigned OpenStack user
-name and password, respectively. 
+name and password, respectively.
 
 ## Authenticating against the Rackspace public cloud
 
@@ -66,16 +66,83 @@ https://mycloud.rackspace.com/a/`username`/account/api-keys
 
 Note that Rackspace UK users will have a different `$endpoint` than US users.
 
+## Setting CURL Options
+
+The **php-opencloud** library uses the standard CURL methods for performing
+HTTP requests. If you need to pass additional options to CURL, you can
+provide them as an optional third argument to the `OpenStack` or
+`Rackspace` constructors. This argument must an associative array of
+option/value pairs. For example, if your code requires you to use an HTTP
+proxy:
+
+	$options = array(CURLOPT_PROXY=>'proxy-name');
+	$cloud = new OpenCloud\OpenStack($endpoint, $credentials, $options);
+
 ## Credential Caching
 
-Note that you only need to authenticate once; the <b>php-opencloud</b> library caches
-your credentials internally and will reuse them until they expire, at which point it
+Note that you only need to authenticate once; the **php-opencloud** library
+caches your credentials in memory and will reuse them until they expire, at
+which point it
 will automatically re-authenticate. The only time you will need to create a new
-`OpenStack` or `Rackspace` object is if your credentials change (for example, if your
+`OpenStack` or `Rackspace` object is if your credentials change (for example,
+if your
 password changes) or to use a different account.
 
-Repeatedly re-authenticating can create a load on the authentication servers and 
-potentially degrade performance for all users. 
+If your PHP process is highly transient (for example, a web page that reloads
+every time someone views it in a browser), then you can cache the credentials
+(for example, using APC or a local disk file) so that you do not have to
+re-authenticate for each request. **php-opencloud** provides two methods for
+exporting and importing the credentials.
+
+Repeatedly re-authenticating can create a load on the authentication servers and
+potentially degrade performance for all users. In addition, some deployments
+will limit the frequency with which you can authenticate.
+
+### Exporting Credentials
+
+The `OpenStack::ExportCredentials()` method exports the current credentials
+(authorization token, expiration, tenant ID, and service catalog)
+as an array:
+
+	$cloud = new OpenStack('URL', array('username'=>'xx','password'=>'yy'));
+	$cloud->Authenticate();	// retrieves credentials from identity service
+	$arr = $cloud->ExportCredentials();
+	store_credentials_in_cache($arr);
+
+In this example, the `Authenticate()` method retrieves the credentials from
+the identity service; the example `store_credentials_in_cache()` function
+(not provided by **php-opencloud**; this is a made-up example) stores the
+credentials in the browser's APC cache. Of course, you could create a function
+to store the credentials in a local file, a database, or whatever meets your
+needs.
+
+## Importing Credentials
+
+The `OpenStack::ImportCredentials()` method imports an array of credentials
+that was created by the `ExportCredentials()` method:
+
+	$cloud = new OpenStack('URL', array('username'=>'xx','password'=>'yy'));
+	$arr = load_credentials_from_cache();
+	$cloud->ImportCredentials($arr);
+
+In this example, the (hypothetical) function `load_credentials_from_cache()`
+loads the credentials that were saved earlier by the `ExportCredentials()`
+method.
+
+Note that the `ImportCredentials()` method must be used *before* any other
+`OpenStack` methods. This is because the `OpenStack` class will automatically
+re-authenticate whenever it needs a token.
+
+	$cloud = new OpenStack('URL', array('username'=>'xx','password'=>'yy'));
+	// this automatically re-authenticates against the identity service
+	$nova = $cloud->Compute(...);
+	// this accidentally overwrites the new credentials with the old one
+	$cloud->ImportCredentials(...);
+
+In other words, this causes no increase in efficiency and, in fact, could
+actually double the number of requests to the identity service (because the
+cached credentials might be invalid, forcing another re-authentication
+on the next request).
 
 What's next?
 ------------
