Added example and update docs

Author: haphan

doc/services/identity/v3/tokens.rst

@@ -43,3 +43,37 @@ Revoke token
 
 .. sample:: identity/v3/tokens/revoke_token.php
 .. refdoc:: OpenStack/Identity/v3/Service.html#method_revokeToken
+
+Cache authentication token
+--------------------------
+
+Use case
+~~~~~~~~
+
+Before one can start calling any API, a very first step that this SDK will do is to authenticate with Identity service
+using user's credential.
+
+If the user's credential is valid, Identity service responses with an authentication token embedded in X-Auth-Token
+header and services catalog. The SDK will then use this authentication token and services catalog in all subsequent API
+calls.
+
+This setup typically works well for command line type of applications. However, for web-based applications, performance
+is undesirable since authentication step adds ~100ms to the response time.
+
+In order to improve performance, SDK allows users to export and store authentication token and re-use it when it is
+still valid.
+
+
+Generate token and persist to file
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. sample:: identity/v3/tokens/export_authentication_token.php
+
+
+For scalability, it is recommended that cached tokens are stored in persistent storage such as memcache or redis instead
+of local file.
+
+Initialize Open Stack using cached authentication token
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. sample:: identity/v3/tokens/use_cached_authentication_token.php

samples/identity/v3/tokens/export_authentication_token.php

@@ -0,0 +1,33 @@
+<?php
+
+require 'vendor/autoload.php';
+
+$params = [
+    'authUrl' => '{authUrl}',
+    'region'  => '{region}',
+    'user'    => [
+        'name'     => '{username}',
+        'password' => '{password}',
+        'domain'   => ['id' => '{domainId}']
+    ],
+    'scope' => [
+        'project' => ['id' => '{projectId}']
+    ]
+];
+
+$openstack = new OpenStack\OpenStack($params);
+
+$identity = $openstack->identityV3();
+
+$token = $identity->generateToken($params);
+
+// Display token expiry
+echo sprintf('Token expires at %s'. PHP_EOL, $token->expires->format('c'));
+
+// Save token to file
+file_put_contents('token.json', json_encode($token->export()));
+
+
+// Alternatively, one may persist token to memcache or redis
+// Redis and memcache then can purge the entry when token expires.
+$memcache->set('token', $token->export, $token->expires->format('U'));

samples/identity/v3/tokens/use_cached_authentication_token.php

@@ -0,0 +1,27 @@
+<?php
+
+require 'vendor/autoload.php';
+
+
+
+$params = [
+    'authUrl' => '{authUrl}',
+    'region'  => '{region}',
+    'user'    => [
+        'name'     => '{username}',
+        'password' => '{password}',
+        'domain'   => ['id' => '{domainId}']
+    ],
+    'scope' => [
+        'project' => ['id' => '{projectId}']
+    ]
+];
+
+$token = json_decode(file_get_contents('token.json'), true);
+
+// Inject cached token to params if token is still fresh
+if ((new \DateTimeImmutable($token['expires_at'])) > (new \DateTimeImmutable('now'))) {
+    $params['cachedToken'] = $token;
+}
+
+$openstack = new OpenStack\OpenStack($params);

src/OpenStack.php

@@ -31,7 +31,7 @@ class OpenStack
      *         ['logger']           = (LoggerInterface)   Must set if debugLog is true   [OPTIONAL]
      *         ['messageFormatter'] = (MessageFormatter)  Must set if debugLog is true   [OPTIONAL]
      *         ['requestOptions']   = (array)             Guzzle Http request options    [OPTIONAL]
-     *         ['cachedCredential'] = (array)             Cached token credential        [OPTIONAL]
+     *         ['cachedToken']      = (array)             Cached token credential        [OPTIONAL]
      *
      * @param Builder $builder
      */