stackforge
/
openstack-sdk-php
Code Issues Proposed changes

IdentityServices and docs converted to PHPDoc. 

Partially implements blueprint phpdoc and completes the blueprint.

Change-Id: Ieb13ad4379d62daf4cb78ed56559adf9aca2f59c
This commit is contained in:
Sam Choi 2014-04-10 02:00:51 -07:00
parent 260eef8195
commit 8bf3e43764
5 changed files with 276 additions and 2181 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1821
config.doxy
View File

File diff suppressed because it is too large Load Diff

213
doc/documentation.php
View File

@ -1,37 +1,37 @@
<?php
/** @mainpage About the OpenStack PHP-Client
/** About the OpenStack PHP-Client
*
* This is the documentation for the OpenStack PHP-Client library.
*
* @section about_package Overview
* Overview
*
* <a href="http://www.openstack.org">OpenStack</a> is open source software for
* @see http://www.openstack.org is open source software for
* building public and private clouds.
*
* The PHP-Client library provides PHP developers with a fully tested,
* robust, and feature-rich library for working with the OpenStack services.
*
* @attention
* Making use of this library will require that you have several pieces of
* account information for your OpenStack account:
* - account ID and secret key: For cases where you want account-wide
* - account ID and secret key: For cases where you want account-wide
* authentication/authorization.
* - username/password: Typically, this is the same username/password you use
* to access the console.
* - tenant ID: This associates an account or user with a bundle of services.
* You can find this information in your console.
* - endpoint: You will need the URL to the OpenStack endpoint responsible for
* <i>authenticating users</i>. This can be found in your console.
* authenticating users. This can be found in your console.
*
* @section where_to_start Where To Start
* Where To Start
*
* Cruising a list of methods and classes is not exactly the best way to get
* started with a library. It's better to know where to start. Here's
* what we suggest:
*
*- There are a few tutorials inside this documentation that will help you
* get started. One explains [Stream Wrappers](@ref streams-tutorial) and
* the other [the library itself](@ref oo-tutorial).
* get started.
* @see streams-tutorial Information about stream wrappers.
* @see oo-tutorial Getting started with the library itself
*- Connecting and logging in is almost inevitably going to be your first
* task. For that, you will want to look at IdentityServices.
*- ObjectStorage (a.k.a. swift) is the cloud storage system. There are
@ -40,46 +40,45 @@
* - You can use the PHP stream wrappers to access your object storage. This
* is explained in StreamWrapper.
*
* @section learn_more Learn More
* Learn More
*
* This documentation is intended to provide a detailed reference to the
* PHP-Client library. To learn more about the APIs and OpenStack visit
* http://api.openstack.org/ and http://docs.openstack.org/.
* @see http://api.openstack.org/
* @see http://docs.openstack.org/
*
* @section intro_example_sw Basic Example: Stream Wrappers
* Basic Example: Stream Wrappers
*
* The super-simple stream API:
*
* @code
* <?php
* // This is only required if you don't have a PSR-4
* // autoloader to do the hard work for you.
* require 'OpenStack/Autoloader.php';
* <?php
* // This is only required if you don't have a PSR-4
* // autoloader to do the hard work for you.
* require 'OpenStack/Autoloader.php';
*
* // If you aren't using a PSR-4 autoloader,
* // you might want to use this:
* \OpenStack\Autoloader::useAutoloader();
* // If you aren't using a PSR-4 autoloader,
* // you might want to use this:
* \OpenStack\Autoloader::useAutoloader();
*
* // Turn on stream wrappers.
* \OpenStack\Bootstrap::useStreamWrappers();
* // Turn on stream wrappers.
* \OpenStack\Bootstrap::useStreamWrappers();
*
* // Create a stream context. You can get this
* // information (including tenant ID) from your
* // OpenStack console.
* $cxt = stream_context_create(array(
* 'username' => 'foo@example.com',
* 'password' => 'secret',
* 'tenantid' => '123456',
* 'endpoint' => 'http://url.from.hpcloud.com/',
* ));
* // Create a stream context. You can get this
* // information (including tenant ID) from your
* // OpenStack console.
* $cxt = stream_context_create(array(
* 'username' => 'foo@example.com',
* 'password' => 'secret',
* 'tenantid' => '123456',
* 'endpoint' => 'http://url.from.hpcloud.com/',
* ));
*
*
* // Get an object from the remote object storage and read it as a string
* // right into $myObject.
* $myObject = file_get_contents('swift://mycontainer/foo.txt', FALSE, $cxt);
* // Get an object from the remote object storage and read it as a string
* // right into $myObject.
* $myObject = file_get_contents('swift://mycontainer/foo.txt', FALSE, $cxt);
*
* ?>
* @endcode
* ?>
*
* With stream wrapper support, you can transparently read and write files to the
* ObjectStorage service without using any fancy API at all. Use the
@ -90,115 +89,111 @@
*- file_get_contents(), stream_get_contents()
*- stat()/fstat()
*- is_readable()/is_writable()
*- And so on (http://us3.php.net/manual/en/ref.filesystem.php).
*- And so on
* @see http://us3.php.net/manual/en/ref.filesystem.php
*
* Learn more about this at OpenStack::Storage::ObjectStorage::StreamWrapper.
* Learn more about this at \OpenStack\Storage\ObjectStorage\StreamWrapper.
*
* @section intro_example_ident Basic Example: Identity Service
* Basic Example: Identity Service
*
* Stream wrappers are nice and all, but
* some of us love fancy APIs. So here's an example using the full API
* to log in and then dump a list of services that are available to you:
*
* @code
* <?php
* // This is only required if you don't have a PSR-4
* // autoloader to do the hard work for you.
* require 'OpenStack/Autoloader.php';
* <?php
* // This is only required if you don't have a PSR-4
* // autoloader to do the hard work for you.
* require 'OpenStack/Autoloader.php';
*
* // If you aren't using a PSR-4 autoloader,
* // you might want to use this:
* \OpenStack\Autoloader::useAutoloader();
* // If you aren't using a PSR-4 autoloader,
* // you might want to use this:
* \OpenStack\Autoloader::useAutoloader();
*
* use \OpenStack\Services\IdentityService;
* use \OpenStack\Services\IdentityService;
*
* // Create a new identity service object, and tell it where to
* // go to authenticate. This URL can be found in your console.
* $identity = new IdentityService('http://get.url.from.hpcloud.com');
* // Create a new identity service object, and tell it where to
* // go to authenticate. This URL can be found in your console.
* $identity = new IdentityService('http://get.url.from.hpcloud.com');
*
* // You can authenticate with a username/password (IdentityService::authenticateAsUser()).
* // In either case you can get the info you need from the console.
* $username = 'foobar';
* $password = 'dgasgasd';
* $tenantId = '56545654';
* // You can authenticate with a username/password (IdentityService::authenticateAsUser()).
* // In either case you can get the info you need from the console.
* $username = 'foobar';
* $password = 'dgasgasd';
* $tenantId = '56545654';
*
* // $token will be your authorization key when you connect to other
* // services. You can also get it from $identity->token().
* $token = $identity->authenticateAsUser($username, $password, $tenantId);
* // $token will be your authorization key when you connect to other
* // services. You can also get it from $identity->token().
* $token = $identity->authenticateAsUser($username, $password, $tenantId);
*
* // Get a listing of all of the services you currently have configured in
* // OpenStack.
* $catalog = $identity->serviceCatalog();
* // Get a listing of all of the services you currently have configured in
* // OpenStack.
* $catalog = $identity->serviceCatalog();
*
* var_dump($catalog);
* var_dump($catalog);
*
* ?>
* @endcode
* ?>
*
*-# Our classes use PHP namespaces to organize components. If you've never used
* them before, don't worry. They're easy to get the hang of.
*-# The Bootstrap class handles setting up OpenStack services. Read about it at OpenStack::Bootstrap.
*-# The IdentityServices class handles authenticating to OpenStack, discovering services, and providing
* access to your account. OpenStack::Services::IdentityService explains the details, but here are
* a few functions you'll want to know:
* - OpenStack::Services::IdentityService::__construct() tells the object where to connect.
* - OpenStack::Services::IdentityService::authenticateAsUser() lets you log
* in with username and password.
* - OpenStack::Services::IdentityService::serviceCatalog() tells you about
* the services you have activated on this account.
*- Our classes use PHP namespaces to organize components. If you've never used
* them before, don't worry. They're easy to get the hang of.
*- The Bootstrap class handles setting up OpenStack services. Read about it at \OpenStack\Bootstrap.
*- The IdentityServices class handles authenticating to OpenStack, discovering services, and providing
* access to your account. \OpenStack\Services\IdentityService explains the details, but here are
* a few functions you'll want to know:
* - \OpenStack\Services\IdentityService::__construct() tells the object where to connect.
* - \OpenStack\Services\IdentityService::authenticateAsUser() lets you log
* in with username and password.
* - \OpenStack\Services\IdentityService::serviceCatalog() tells you about
* the services you have activated on this account.
*
* @section intro_example_swift Basic Example: Object Storage
* Basic Example: Object Storage
*
* Assuming you have an object storage instance available in your service
* catalog, we could continue on with something like this:
*
* @code
* <?php
* // The explicit way:
* // Find out where our ObjectStorage instance lives:
* // $storageList = $identity->serviceCatalog('object-storage');
* // $objectStorageUrl = storageList[0]['endpoints'][0]['publicURL'];
* <?php
* // The explicit way:
* // Find out where our ObjectStorage instance lives:
* // $storageList = $identity->serviceCatalog('object-storage');
* // $objectStorageUrl = storageList[0]['endpoints'][0]['publicURL'];
*
* // Create a new ObjectStorage instance:
* // $objectStore = new \OpenStack\Storage\ObjectStorage($token, $objectStorageUrl);
* // Create a new ObjectStorage instance:
* // $objectStore = new \OpenStack\Storage\ObjectStorage($token, $objectStorageUrl);
*
* // Or let ObjectStorage figure out which instance to use:
* $objectStore = \OpenStack\Storage\ObjectStorage::newFromIdentity($identity);
* // Or let ObjectStorage figure out which instance to use:
* $objectStore = \OpenStack\Storage\ObjectStorage::newFromIdentity($identity);
*
* // List containers:
* print_r($objectStore->containers());
* // List containers:
* print_r($objectStore->containers());
*
* // Get a container named 'stuff':
* $container = $objectStore->container('stuff');
* // Get a container named 'stuff':
* $container = $objectStore->container('stuff');
*
* // List all of the objects in that container:
* print_r($container->objects());
* // List all of the objects in that container:
* print_r($container->objects());
*
* // Get an object named 'example.txt'
* $obj = $container->object('example.txt');
* // Get an object named 'example.txt'
* $obj = $container->object('example.txt');
*
* // Print that object's contents:
* print $obj->content();
* // Print that object's contents:
* print $obj->content();
*
* // Actually, since it implements __tostring, we could do this:
* print $obj;
* ?>
* @endcode
* // Actually, since it implements __tostring, we could do this:
* print $obj;
* ?>
*
* This shows you a few methods for accessing objects and containers on your
* OpenStack::Storage::ObjectStorage account. There are many functions for
* \OpenStack\Storage\ObjectStorage account. There are many functions for
* creating and modifying containers and objects, too.
*
*- OpenStack::Storage::ObjectStorage is where you will start.
*- Container services are in OpenStack::Storage::ObjectStorage::Container
*- \OpenStack\Storage\ObjectStorage is where you will start.
*- Container services are in \OpenStack\Storage\ObjectStorage\Container
*- There are two classes for objects:
* - OpenStack::Storage::ObjectStorage::Object is for creating new objects.
* - OpenStack::Storage::ObjectStorage::RemoteObject provides better network
* - \OpenStack\Storage\ObjectStorage\Object is for creating new objects.
* - \OpenStack\Storage\ObjectStorage\RemoteObject provides better network
* performance when reading objects.
*
*/
// Note that Doxygen assumes that dot (.) is the namespace separator in
// package descriptions.
/**
* @package OpenStack
* The OpenStack PHP-Client library.
@ -227,7 +222,7 @@
* @package OpenStack.Storage.ObjectStorage
* Classes specific to ObjectStorage.
*
* The main class is OpenStack::Storage::ObjectStorage.
* The main class is \OpenStack\Storage\ObjectStorage.
*/
/**
* @package OpenStack.Transport

7
doc/oo-tutorial.md
View File

@ -491,11 +491,4 @@ OpenStack and works with object storage. Clearly, this only scratches the
surface of what the OpenStack PHP-Client library does. But hopefully this is
enough to get you started with the library.
The entire library is well documented, and the documentation is
[available online](https://FIXME). You can also build a
local copy by installing [doxygen](http://www.stack.nl/~dimitri/doxygen)
(if you haven't already) and running `make docs` in the root of the
OpenStack PHP-Client project. This will place the generated documents in
`docs/api/html`.
\see oo-tutorial-code.php

21
doc/style.md
View File

@ -8,7 +8,7 @@ style.
- Read the [coding standards](https://github.com/mattfarina/Coding-Standards)
to learn why we code the way we do.
- Read the [doxygen manual](http://www.stack.nl/~dimitri/doxygen)
- Read about [PHPDoc](http://www.phpdoc.org/)
if you're curious about our source code documentation.
- Two spaces, no tabs.
- WE LOVE GITHUB ISSUES AND PULL REQUESTS
@ -117,21 +117,4 @@ free to suggest improvements on either side of the scales.
## Documentation Style
This project is documented with Doxygen, and the configuration file used
is available in ./config.doxy in this project.
The following conventions are used:
- In documentation, namespaces are separated with double-colon (::) instead of
backslash characters (\\). This is because backslash characters have
special meaning to Doxygen, and cannot be used as namespace separators.
- We use \@retval instead of \@return. This special marker was added to
Doxygen for languages like PHP where the return type is "optional". We
try to always specify a return type, thus we use retval.
### Markdown and Doxygen >= 1.8
Since Doxygen 1.8.0, Doxygen boasts native support for Markdown. Where
possible, we write documentation in Markdown, which makes it both
readable in the source code form, and also a fully integrated part of
the API documentation.
This project is documented with PHPDoc.

395
src/OpenStack/Services/IdentityService.php
View File

@ -15,8 +15,6 @@
limitations under the License.
============================================================================ */
/**
* @file
*
* This file contains the main IdentityService class.
*/
@ -33,7 +31,7 @@ namespace OpenStack\Services;
* - Obtain a list of the services currently available with a token
* - Associate with tenants using tenant IDs.
*
* @b AUTHENTICATION
* AUTHENTICATION
*
* The authentication process consists of a single transaction during which the
* client (us) submits credentials and the server verifies those credentials,
@ -47,7 +45,7 @@ namespace OpenStack\Services;
*
* Other mechanisms may be supported in the future.
*
* @b TENANTS
* TENANTS
*
* Services are associated with tenants. A token is returned when
* authentication succeeds. It *may* be associated with a tenant. If it is not,
@ -63,7 +61,7 @@ namespace OpenStack\Services;
* - After authentication, "rescope" the token to attach it to a tenant. This
* is done with the rescope() method.
*
* <b>Where do I get a tenant ID?</b>
* Where do I get a tenant ID?
*
* There are two notable places to get this information:
*
@ -73,41 +71,39 @@ namespace OpenStack\Services;
* OpenStack users can find their tenant ID in the console along with their
* username and password.
*
* @b EXAMPLE
* EXAMPLE
*
* The following example illustrates typical use of this class.
*
* @code
* <?php
* // You may need to use \OpenStack\Bootstrap to set things up first.
* <?php
* // You may need to use \OpenStack\Bootstrap to set things up first.
*
* use \OpenStack\Services\IdentityService;
* use \OpenStack\Services\IdentityService;
*
* // Create a new object with the endpoint URL (no version number)
* $ident = new IdentityService('https://example.com:35357');
* // Create a new object with the endpoint URL (no version number)
* $ident = new IdentityService('https://example.com:35357');
*
* // Authenticate and set the tenant ID simultaneously.
* $ident->authenticateAsUser('me@example.com', 'password', '1234567');
* // Authenticate and set the tenant ID simultaneously.
* $ident->authenticateAsUser('me@example.com', 'password', '1234567');
*
* // The token to use when connecting to other services:
* $token = $ident->token();
* // The token to use when connecting to other services:
* $token = $ident->token();
*
* // The tenant ID.
* $tenant = $ident->tenantId();
* // The tenant ID.
* $tenant = $ident->tenantId();
*
* // Details about what services this token can access.
* $services = $ident->serviceCatalog();
* // Details about what services this token can access.
* $services = $ident->serviceCatalog();
*
* // List all available tenants.
* $tenants = $ident->tenants();
* // List all available tenants.
* $tenants = $ident->tenants();
*
* // Switch to a different tenant.
* $ident->rescope($tenants[0]['id']);
* // Switch to a different tenant.
* $ident->rescope($tenants[0]['id']);
*
* ?>
* @endcode
* ?>
*
* <b>PERFORMANCE CONSIDERATIONS</b>
* PERFORMANCE CONSIDERATIONS
*
* The following methods require network requests:
*
@ -116,7 +112,7 @@ namespace OpenStack\Services;
* - tenants()
* - rescope()
*
* <b>Serializing</b>
* Serializing
*
* IdentityService has been intentionally built to serialize well.
* This allows implementors to cache IdentityService objects rather
@ -128,10 +124,12 @@ class IdentityService /*implements Serializable*/ {
* The version of the API currently supported.
*/
const API_VERSION = '2.0';
/**
* The full OpenStack accept type.
*/
const ACCEPT_TYPE = 'application/json';
// This is no longer supported.
//const ACCEPT_TYPE = 'application/vnd.openstack.identity+json;version=2.0';
@ -150,18 +148,16 @@ class IdentityService /*implements Serializable*/ {
*
* This is an associative array looking like this:
*
* @code
* <?php
* array(
* 'id' => 'auth_123abc321defef99',
* // Only non-empty for username/password auth.
* 'tenant' => array(
* 'id' => '123456',
* 'name' => 'matt.butcher@hp.com',
* ),
* 'expires' => '2012-01-24T12:46:01.682Z'
* );
* @endcode
* <?php
* array(
* 'id' => 'auth_123abc321defef99',
* // Only non-empty for username/password auth.
* 'tenant' => array(
* 'id' => '123456',
* 'name' => 'matt.butcher@hp.com',
* ),
* 'expires' => '2012-01-24T12:46:01.682Z'
* );
*/
protected $tokenDetails;
@ -177,27 +173,23 @@ class IdentityService /*implements Serializable*/ {
*
* Each object is bound to a particular identity services endpoint.
*
* For the URL, you are advised to use the version <i>without</i> a
* For the URL, you are advised to use the version without a
* version number at the end, e.g. http://cs.example.com/ rather
* than http://cs.example.com/v2.0. The version number must be
* controlled by the library.
*
* @attention
* If a version is included in the URI, the library will attempt to use
* that URI.
*
* @code
* <?php
* $cs = new \OpenStack\Services\IdentityService('http://example.com');
* $token = $cs->authenticateAsUser($username, $password);
* ?>
* @endcode
* <?php
* $cs = new \OpenStack\Services\IdentityService('http://example.com');
* $token = $cs->authenticateAsUser($username, $password);
* ?>
*
* @param string $url
* An URL pointing to the Identity Services endpoint. Note that you do
* not need the version identifier in the URL, as version information
* is sent in the HTTP headers rather than in the URL. <b>The URL
* should <i>always</i> be to an SSL/TLS encrypted endpoint.</b>.
* @param string $url An URL pointing to the Identity Services endpoint. Note
* that you do not need the version identifier in the URL, as version
* information is sent in the HTTP headers rather than in the URL. The URL
* should always be to an SSL/TLS encrypted endpoint.
*/
public function __construct($url) {
$parts = parse_url($url);
@ -216,9 +208,7 @@ class IdentityService /*implements Serializable*/ {
* This includes version number, so in that regard it is not an identical
* URL to the one passed into the constructor.
*
* @retval string
* @return string
* The complete URL to the identity services endpoint.
* @return string The complete URL to the identity services endpoint.
*/
public function url() {
return $this->endpoint;
@ -227,39 +217,36 @@ class IdentityService /*implements Serializable*/ {
/**
* Send an authentication request.
*
* @remark EXPERT: This allows authentication requests at a low level. For simple
* EXPERT: This allows authentication requests at a low level. For simple
* authentication requests using a username, see the
* authenticateAsUser() method.
*
* Here is an example of username/password-based authentication done with
* the authenticate() method:
* @code
* <?php
* $cs = new \OpenStack\Services\IdentityService($url);
* $ops = array(
* 'passwordCredentials' => array(
* 'username' => $username,
* 'password' => $password,
* ),
* 'tenantId' => $tenantId,
* );
* $token = $cs->authenticate($ops);
* ?>
* @endcode
*
* <?php
* $cs = new \OpenStack\Services\IdentityService($url);
* $ops = array(
* 'passwordCredentials' => array(
* 'username' => $username,
* 'password' => $password,
* ),
* 'tenantId' => $tenantId,
* );
* $token = $cs->authenticate($ops);
* ?>
*
* Note that the same authentication can be done by authenticateAsUser().
*
* @param array $ops
* An associative array of authentication operations and their respective
* parameters.
* @retval string
* @return string
* The token. This is returned for simplicity. The full response is used
* to populate this object's service catalog, etc. The token is also
* retrievable with token().
* @throws OpenStack::Transport::AuthorizationException
* @param array $ops An associative array of authentication operations and
* their respective parameters.
*
* @return string The token. This is returned for simplicity. The full
* response is used to populate this object's service catalog, etc. The
* token is also retrievable with token().
* @throws \OpenStack\Transport\AuthorizationException
* If authentication failed.
* @throws OpenStack::Exception
* @throws \OpenStack\Exception
* For abnormal network conditions. The message will give an indication as
* to the underlying problem.
*/
@ -290,7 +277,7 @@ class IdentityService /*implements Serializable*/ {
}
/**
* Authenticate to Identity Services with username, password, and either
* Authenticate to Identity Services with username, password, and either
* tenant ID or tenant Name.
*
* Given a OpenStack username and password, authenticate to Identity Services.
@ -308,21 +295,15 @@ class IdentityService /*implements Serializable*/ {
* Other authentication methods:
* - authenticate()
*
* @param string $username
* A valid username.
* @param string $password
* A password string.
* @param string $tenantId
* The tenant ID. This can be obtained through the
* @param string $username A valid username.
* @param string $password A password string.
* @param string $tenantId The tenant ID. This can be obtained through the
* OpenStack console.
* @param string $tenantName
* The tenant Name. This can be obtained through the
* @param string $tenantName The tenant Name. This can be obtained through the
* OpenStack console.
* @throws OpenStack::Transport::AuthorizationException
* If authentication failed.
* @throws OpenStack::Exception
* For abnormal network conditions. The message will give an indication as
* to the underlying problem.
* @throws \OpenStack\Transport\AuthorizationException If authentication failed.
* @throws \OpenStack\Exception For abnormal network conditions. The message
* will give an indication as to the underlying problem.
*/
public function authenticateAsUser($username, $password, $tenantId = NULL, $tenantName = NULL) {
$ops = array(
@ -350,9 +331,7 @@ class IdentityService /*implements Serializable*/ {
* This will not be populated until after one of the authentication
* methods has been run.
*
* @retval string
* @return string
* The token ID to be used in subsequent calls.
* @return string The token ID to be used in subsequent calls.
*/
public function token() {
return $this->tokenDetails['id'];
@ -367,9 +346,7 @@ class IdentityService /*implements Serializable*/ {
* This will not be populated until after an authentication method has been
* run.
*
* @retval string
* @return string
* The tenant ID if available, or NULL.
* @return string The tenant ID if available, or NULL.
*/
public function tenantId() {
if (!empty($this->tokenDetails['tenant']['id'])) {
@ -386,9 +363,7 @@ class IdentityService /*implements Serializable*/ {
* This will not be populated until after an authentication method has been
* run.
*
* @retval string
* @return string
* The tenant name if available, or NULL.
* @return string The tenant name if available, or NULL.
*/
public function tenantName() {
if (!empty($this->tokenDetails['tenant']['name'])) {
@ -407,23 +382,19 @@ class IdentityService /*implements Serializable*/ {
* - tenant_id: The tenant ID of the authenticated user.
* - tenant_name: The username of the authenticated user.
*
* @code
* <?php
* array(
* 'id' => 'auth_123abc321defef99',
* 'tenant' => array(
* 'id' => '123456',
* 'name' => 'matt.butcher@hp.com',
* ),
* 'expires' => '2012-01-24T12:46:01.682Z'
* );
* @endcode
* <?php
* array(
* 'id' => 'auth_123abc321defef99',
* 'tenant' => array(
* 'id' => '123456',
* 'name' => 'matt.butcher@hp.com',
* ),
* 'expires' => '2012-01-24T12:46:01.682Z'
* );
*
* This will not be populated until after authentication has been done.
*
* @retval array
* @return array
* An associative array of details.
* @return array An associative array of details.
*/
public function tokenDetails() {
return $this->tokenDetails;
@ -436,11 +407,9 @@ class IdentityService /*implements Serializable*/ {
* machine's local timestamp with the server's expiration time stamp. A
* mis-configured machine timestamp could give spurious results.
*
* @retval boolean
* @return boolean
* This will return FALSE if there is a current token and it has
* not yet expired (according to the date info). In all other cases
* it returns TRUE.
* @return boolean This will return FALSE if there is a current token and it
* has not yet expired (according to the date info). In all other cases it
* returns TRUE.
*/
public function isExpired() {
$details = $this->tokenDetails();
@ -476,34 +445,33 @@ class IdentityService /*implements Serializable*/ {
*
* The return value is an indexed array of associative arrays, where each assoc
* array describes an individual service.
* @code
* <?php
* array(
* array(
* 'name' : 'Object Storage',
* 'type' => 'object-store',
* 'endpoints' => array(
* 'tenantId' => '123456',
* 'adminURL' => 'https://example.hpcloud.net/1.0',
* 'publicURL' => 'https://example.hpcloud.net/1.0/123456',
* 'region' => 'region-a.geo-1',
* 'id' => '1.0',
* ),
* ),
* array(
* 'name' => 'Identity',
* 'type' => 'identity'
* 'endpoints' => array(
* 'publicURL' => 'https://example.hpcloud.net/1.0/123456',
* 'region' => 'region-a.geo-1',
* 'id' => '2.0',
* 'list' => 'http://example.hpcloud.net/extension',
* ),
* )
*
* );
* ?>
* @endcode
* <?php
* array(
* array(
* 'name' : 'Object Storage',
* 'type' => 'object-store',
* 'endpoints' => array(
* 'tenantId' => '123456',
* 'adminURL' => 'https://example.hpcloud.net/1.0',
* 'publicURL' => 'https://example.hpcloud.net/1.0/123456',
* 'region' => 'region-a.geo-1',
* 'id' => '1.0',
* ),
* ),
* array(
* 'name' => 'Identity',
* 'type' => 'identity'
* 'endpoints' => array(
* 'publicURL' => 'https://example.hpcloud.net/1.0/123456',
* 'region' => 'region-a.geo-1',
* 'id' => '2.0',
* 'list' => 'http://example.hpcloud.net/extension',
* ),
* )
*
* );
* ?>
*
* This will not be populated until after authentication has been done.
*
@ -520,10 +488,7 @@ class IdentityService /*implements Serializable*/ {
*
* @todo Paging on the service catalog is not yet implemented.
*
* @retval array
* @return array
* An associative array representing
* the service catalog.
* @return array An associative array representing the service catalog.
*/
public function serviceCatalog($type = NULL) {
// If no type is specified, return the entire
@ -549,28 +514,25 @@ class IdentityService /*implements Serializable*/ {
* user, including the user's username and roles.
*
* The returned data is structured like this:
* @code
* <?php
* array(
* 'name' => 'matthew.butcher@hp.com',
* 'id' => '1234567890'
* 'roles' => array(
*
* <?php
* array(
* 'name' => 'domainuser',
* 'serviceId' => '100',
* 'id' => '000100400010011',
* ),
* // One array for each role...
* ),
* )
* ?>
* @endcode
* 'name' => 'matthew.butcher@hp.com',
* 'id' => '1234567890'
* 'roles' => array(
* array(
* 'name' => 'domainuser',
* 'serviceId' => '100',
* 'id' => '000100400010011',
* ),
* // One array for each role...
* ),
* )
* ?>
*
* This will not have data until after authentication has been done.
*
* @retval array
* @return array
* An associative array, as described above.
* @return array An associative array, as described above.
*/
public function user() {
return $this->userDetails;
@ -585,32 +547,26 @@ class IdentityService /*implements Serializable*/ {
*
* Returned data will follow this format:
*
* @code
* <?php
* array(
* array(
* "id" => "395I91234514446",
* "name" => "Banking Tenant Services",
* "description" => "Banking Tenant Services for TimeWarner",
* "enabled" => TRUE,
* "created" => "2011-11-29T16:59:52.635Z",
* "updated" => "2011-11-29T16:59:52.635Z",
* ),
* );
* ?>
* @endcode
* <?php
* array(
* array(
* "id" => "395I91234514446",
* "name" => "Banking Tenant Services",
* "description" => "Banking Tenant Services for TimeWarner",
* "enabled" => TRUE,
* "created" => "2011-11-29T16:59:52.635Z",
* "updated" => "2011-11-29T16:59:52.635Z",
* ),
* );
* ?>
*
* Note that this method invokes a new request against the remote server.
*
* @retval array
* @return array
* An indexed array of tenant info. Each entry will be an associative
* array containing tenant details.
* @throws OpenStack::Transport::AuthorizationException
* If authentication failed.
* @throws OpenStack::Exception
* For abnormal network conditions. The message will give an indication as
* to the underlying problem.
* @return array An indexed array of tenant info. Each entry will be an
* associative array containing tenant details.
* @throws \OpenStack\Transport\AuthorizationException If authentication failed.
* @throws \OpenStack\Exception For abnormal network conditions. The message
* will give an indication as to the underlying problem.
*/
public function tenants($token = NULL) {
$url = $this->url() . '/tenants';
@ -636,7 +592,7 @@ class IdentityService /*implements Serializable*/ {
}
/**
* @see OpenStack::Services::IdentityService::rescopeUsingTenantId()
* @see \OpenStack\Services\IdentityService::rescopeUsingTenantId()
* @deprecated
*/
public function rescope($tenantId) {
@ -660,19 +616,15 @@ class IdentityService /*implements Serializable*/ {
* - Change a token from one tenant ID to another (re-scoping).
* - Remove the tenant ID from a scoped token (unscoping).
*
* @param string $tenantId
* The tenant ID that this present token should be bound to. If this is the
* empty string (`''`), the present token will be "unscoped" and its tenant
* ID will be removed.
* @param string $tenantId The tenant ID that this present token should be
* bound to. If this is the empty string (`''`), the present token will be
* "unscoped" and its tenant ID will be removed.
*
* @retval string
* @return string
* The authentication token.
* @throws OpenStack::Transport::AuthorizationException
* If authentication failed.
* @throws OpenStack::Exception
* For abnormal network conditions. The message will give an indication as
* to the underlying problem.
* @return string The authentication token.
* @throws \OpenStack\Transport\AuthorizationException If authentication
* failed.
* @throws \OpenStack\Exception For abnormal network conditions. The message
* will give an indication as to the underlying problem.
*/
public function rescopeUsingTenantId($tenantId) {
$url = $this->url() . '/tokens';
@ -718,19 +670,14 @@ class IdentityService /*implements Serializable*/ {
* - Change a token from one tenant ID to another (re-scoping).
* - Remove the tenant ID from a scoped token (unscoping).
*
* @param string $tenantName
* The tenant name that this present token should be bound to. If this is the
* empty string (`''`), the present token will be "unscoped" and its tenant
* name will be removed.
* @param string $tenantName The tenant name that this present token should be
* bound to. If this is the empty string (`''`), the present token will be
* "unscoped" and its tenant name will be removed.
*
* @retval string
* @return string
* The authentication token.
* @throws OpenStack::Transport::AuthorizationException
* If authentication failed.
* @throws OpenStack::Exception
* For abnormal network conditions. The message will give an indication as
* to the underlying problem.
* @return string The authentication token.
* @throws \OpenStack\Transport\AuthorizationException If authentication failed.
* @throws \OpenStack\Exception For abnormal network conditions. The message
* will give an indication as to the underlying problem.
*/
public function rescopeUsingTenantName($tenantName) {
$url = $this->url() . '/tokens';
@ -765,12 +712,10 @@ class IdentityService /*implements Serializable*/ {
* This parses the JSON data and parcels out the data to the appropriate
* fields.
*
* @param object $response OpenStack::Transport::Response
* A response object.
* @param object $response \OpenStack\Transport\Response A response object.
*
* @retval OpenStack::Services::IdentityService
* @return \OpenStack\Services\IdentityService
* $this for the current object so it can be used in chaining.
* @return \OpenStack\Services\IdentityService $this for the current object so
* it can be used in chaining.
*/
protected function handleResponse($response) {
$json = json_decode($response->content(), TRUE);
@ -803,4 +748,4 @@ class IdentityService /*implements Serializable*/ {
}
*/
}
}