Access to ObjectStorage (Swift). More...

Public Member Functions
	__construct ($authToken, $url)
	Construct a new ObjectStorage object.
	useCDN ($cdn)
	Indicate that this ObjectStorage instance should use the given CDN service.
	hasCDN ()
	cdnUrl ($containerName, $ssl=TRUE)
	Return the CDN URL for a particular container.
	token ()
	Get the authentication token.
	url ()
	Get the URL endpoint.
	containers ($limit=0, $marker=NULL)
	Fetch a list of containers for this account.
	container ($name)
	Get a single specific container.
	hasContainer ($name)
	Check to see if this container name exists.
	createContainer ($name, ACL $acl=NULL, $metadata=array())
	Create a container with the given name.
	updateContainer ($name, ACL $acl=NULL, $metadata=array())
	Alias of createContainer().
	changeContainerACL ($name, ACL $acl)
	Change the container's ACL.
	deleteContainer ($name)
	Delete an empty container.
	accountInfo ()
	Retrieve account info.

Static Public Member Functions
static	newFromSwiftAuth ($account, $key, $url)
	Create a new instance after getting an authenitcation token.
static	newFromIdentity ($identity, $region=ObjectStorage::DEFAULT_REGION)
	Given an IdentityServices instance, create an ObjectStorage instance.
static	newFromServiceCatalog ($catalog, $authToken, $region=ObjectStorage::DEFAULT_REGION)
	Given a service catalog and an token, create an ObjectStorage instance.

Public Attributes
const	SERVICE_TYPE = 'object-store'
	The name of this service type in HPCloud.
const	API_VERSION = '1'
const	DEFAULT_REGION = 'region-a.geo-1'

Protected Member Functions
	get ($url, $jsonDecode=TRUE)
	Do a GET on Swift.
	req ($url, $method= 'GET', $jsonDecode=TRUE, $body= '')
	Internal request issuing command.

Protected Attributes
	$token = NULL
	The authorization token.
	$url = NULL
	The URL to the Swift endpoint.
	$cdnContainers
	CDN containers.

Detailed Description

Access to ObjectStorage (Swift).

This is the primary piece of the Object Oriented representation of the Object Storage service. Developers wishing to work at a low level should use this API.

There is also a stream wrapper interface that exposes ObjectStorage to PHP's streams system. For common use of an object store, you may prefer to use that system. (See HPCloud::Bootstrap).

When constructing a new ObjectStorage object, you will need to know what kind of authentication you are going to perform. Older implementations of OpenStack provide a separate authentication mechanism for Swift. You can use ObjectStorage::newFromSwiftAuth() to perform this type of authentication.

Newer versions use the IdentityServices authentication mechanism (see HPCloud::Services::IdentityServices). That method is the preferred method.

Common Tasks

Create a new container with createContainer().
List containers with containers().
Remove a container with deleteContainer().

Todo:: ObjectStorage is not yet constrained to a particular version of the API. It attempts to use whatever version is passed in to the URL. This is different than IdentityServices and CDN, which use a fixed version.

Definition at line 70 of file ObjectStorage.php.

Constructor & Destructor Documentation

__construct	(	$authToken,
		$url
	)

Construct a new ObjectStorage object.

Use this if newFromServiceCatalog() does not meet your needs.

Parameters

string	$authToken	A token that will be included in subsequent requests to validate that this client has authenticated correctly.
string	$url	The URL to the endpoint. This typically is returned after authentication.

Definition at line 236 of file ObjectStorage.php.

References ObjectStorage\$url, ObjectStorage\token(), and ObjectStorage\url().

Member Function Documentation

accountInfo ( )

Retrieve account info.

This returns information about:

The total bytes used by this Object Storage instance (bytes).
The number of containers (count).

Return values

array

Returns

array An associative array of account info. Typical keys are:

bytes: Bytes consumed by existing content.
containers: Number of containers.
objects: Number of objects.

Exceptions

HPCloud::Transport::AuthorizationException if the user credentials are invalid or have expired.

Definition at line 655 of file ObjectStorage.php.

References ObjectStorage\$url, ObjectStorage\req(), and ObjectStorage\url().

cdnUrl	(	$containerName,
		$ssl = `TRUE`
	)

Return the CDN URL for a particular container.

If CDN is enabled, this will attempt to get the URL to the CDN endpoint for the given container.

Parameters

string	$containerName	The name of the container.
boolean	$ssl	If this is TRUE (default), get the URL to the SSL CDN; otherwise get the URL to the plain HTTP CDN.

Return values

string

Returns: string The URL to the CDN container, or NULL if no such URL is found.

Definition at line 303 of file ObjectStorage.php.

References $key.

Referenced by RemoteObject\fetchObject(), Container\object(), Container\proxyObject(), RemoteObject\url(), RemoteObject\useCDN(), and Container\useCDN().

changeContainerACL	(		$name,
		ACL	$acl
	)

Change the container's ACL.

This will attempt to change the ACL on a container. If the container does not already exist, it will be created first, and then the ACL will be set. (This is a relic of the OpenStack Swift implementation, which uses the same HTTP verb to create a container and to set the ACL.)

Parameters

string	$name	The name of the container.
object	$acl	HPCloud::Storage::ObjectStorage::ACL An ACL. To make the container publically readable, use ACL::makePublic().

Return values

boolean

Returns: boolean TRUE if the cointainer was created, FALSE otherwise.

Definition at line 581 of file ObjectStorage.php.

References $name, and ObjectStorage\createContainer().

container ( $name )

Get a single specific container.

This loads only the named container from the remote server.

Parameters

string $name The name of the container to load.

Return values

HPCloud::Storage::ObjectStorage::Container

Returns: A container.

Exceptions

HPCloud::Transport::FileNotFoundException if the named container is not found on the remote server.

Definition at line 409 of file ObjectStorage.php.

References $container, $name, ObjectStorage\$url, Container\newFromResponse(), ObjectStorage\req(), ObjectStorage\token(), and ObjectStorage\url().

Referenced by ObjectStorage\hasContainer(), StreamWrapper\stream_open(), StreamWrapper\stream_stat(), and StreamWrapper\writeRemote().

containers	(	$limit = `0`,
		$marker = `NULL`
	)

Fetch a list of containers for this account.

By default, this fetches the entire list of containers for the given account. If you have more than 10,000 containers (who wouldn't?), you will need to use $marker for paging.

If you want more controlled paging, you can use $limit to indicate the number of containers returned per page, and $marker to indicate the last container retrieved.

Containers are ordered. That is, they will always come back in the same order. For that reason, the pager takes $marker (the name of the last container) as a paging parameter, rather than an offset number.

Todo:: For some reason, ACL information does not seem to be returned in the JSON data. Need to determine how to get that. As a stop-gap, when a container object returned from here has its ACL requested, it makes an additional round-trip to the server to fetch that data.

Parameters

int	$limit	The maximum number to return at a time. The default is – brace yourself – 10,000 (as determined by OpenStack. Implementations may vary).
string	$marker	The name of the last object seen. Used when paging.

Return values

array

Returns: array An associative array of containers, where the key is the container's name and the value is an HPCloud::Storage::ObjectStorage::Container object. Results are ordered in server order (the order that the remote host puts them in).

Definition at line 369 of file ObjectStorage.php.

References $container, ObjectStorage\$url, Container\newFromJSON(), ObjectStorage\token(), and ObjectStorage\url().

createContainer	(		$name,
		ACL	$acl = `NULL`,
			$metadata = `array()`
	)

Create a container with the given name.

This creates a new container on the ObjectStorage server with the name provided in $name.

A boolean is returned when the operation did not generate an error condition.

TRUE means that the container was created.
FALSE means that the container was not created because it already exists.

Any actual error will cause an exception to be thrown. These will be the HTTP-level exceptions.

ACLs

Swift supports an ACL stream that allows for specifying (with certain caveats) various levels of read and write access. However, there are two standard settings that cover the vast majority of cases.

Make the resource private: This grants read and write access to ONLY the creating account. This is the default; it can also be specified with ACL::makeNonPublic().
Make the resource public: This grants READ permission to any requesting host, yet only allows the creator to WRITE to the object. This level can be granted by ACL::makePublic().

Note that ACLs operate at a container level. Thus, marking a container public will allow access to ALL objects inside of the container.

To find out whether an existing container is public, you can write something like this:

<?php
// Get the container.
$container = $objectStorage->container('my_container');
//Check the permission on the ACL:
$boolean = $container->acl()->isPublic();
?>

For details on ACLs, see HPCloud::Storage::ObjectStorage::ACL.

Parameters

string	$name	The name of the container.
object	$acl	HPCloud::Storage::ObjectStorage::ACL An access control list object. By default, a container is non-public (private). To change this behavior, you can add a custom ACL. To make the container publically readable, you can use this: HPCloud::Storage::ObjectStorage::ACL::makePublic().
array	$metadata	An associative array of metadata to attach to the container.

Return values

boolean

Returns: boolean TRUE if the container was created, FALSE if the container was not created because it already exists.

Definition at line 518 of file ObjectStorage.php.

References $name, ObjectStorage\$url, Container\CONTAINER_METADATA_HEADER_PREFIX, Container\generateMetadataHeaders(), ObjectStorage\token(), and ObjectStorage\url().

Referenced by ObjectStorage\changeContainerACL(), and ObjectStorage\updateContainer().

deleteContainer ( $name )

Delete an empty container.

Given a container name, this attempts to delete the container in the object storage.

The container MUST be empty before it can be deleted. If it is not, an HPCloud::Storage::ObjectStorage::ContainerNotEmptyException will be thrown.

Parameters

string $name The name of the container.

Return values

boolean

Returns: boolean TRUE if the container was deleted, FALSE if the container was not found (and hence, was not deleted).

Exceptions

HPCloud::Storage::ObjectStorage::ContainerNotEmptyException	if the container is not empty.
HPCloud::Exception	if an unexpected response code is returned. While this should never happen on HPCloud servers, forks of OpenStack may choose to extend object storage in a way that results in a non-standard code.

Definition at line 610 of file ObjectStorage.php.

References $name, ObjectStorage\$url, ObjectStorage\req(), and ObjectStorage\url().

get	(	$url,
		$jsonDecode = `TRUE`
	)

protected

Do a GET on Swift.

This is a convenience method that handles the most common case of Swift requests.

Definition at line 674 of file ObjectStorage.php.

References ObjectStorage\$url, and ObjectStorage\req().

hasCDN ( )

Definition at line 283 of file ObjectStorage.php.

hasContainer ( $name )

Check to see if this container name exists.

This method directly checks the remote server. Calling container() or containers() might be more efficient if you plan to work with the resulting container.

Parameters

string $name The name of the container to test.

Return values

boolean

Returns: boolean TRUE if the container exists, FALSE if it does not.

Exceptions

HPCloud::Exception If an unexpected network error occurs.

Definition at line 445 of file ObjectStorage.php.

References $container, $name, and ObjectStorage\container().

static newFromIdentity	(	$identity,
		$region = `ObjectStorage::DEFAULT_REGION`
	)

static

Given an IdentityServices instance, create an ObjectStorage instance.

This constructs a new ObjectStorage from an authenticated instance of an HPCloud::Services::IdentityServices object.

Parameters

HPCloud::Services::IdentityServices $identity An identity services object that already has a valid token and a service catalog.

Return values

HPCloud::Storage::ObjectStorage

Returns: A new ObjectStorage instance.

Definition at line 181 of file ObjectStorage.php.

References ObjectStorage\newFromServiceCatalog().

static newFromServiceCatalog	(	$catalog,
		$authToken,
		$region = `ObjectStorage::DEFAULT_REGION`
	)

static

Given a service catalog and an token, create an ObjectStorage instance.

The IdentityServices object contains a service catalog listing all of the services to which the present account has access.

This builder can scan the catalog and generate a new ObjectStorage instance pointed to the first object storage endpoint in the catalog.

Parameters

array	$catalog	The serice catalog from IdentityServices::serviceCatalog(). This can be either the entire catalog or a catalog filtered to just ObjectStorage::SERVICE_TYPE.
string	$authToken	The auth token returned by IdentityServices.

Return values

HPCloud::Storage::ObjectStorage

Returns: A new ObjectStorage instance.

Definition at line 206 of file ObjectStorage.php.

References $catalog, and $endpoint.

Referenced by StreamWrapper\initializeCDN(), StreamWrapper\initializeObjectStorage(), and ObjectStorage\newFromIdentity().

static newFromSwiftAuth	(	$account,
		$key,
		$url
	)

static

Create a new instance after getting an authenitcation token.

THIS METHOD IS DEPRECATED. OpenStack now uses Keyston to authenticate. You should use HPCloud::Services::IdentityServices to authenticate. Then use this class's constructor to create an object.

This uses the legacy Swift authentication facility to authenticate to swift, get a new token, and then create a new ObjectStorage instance with that token.

To use the legacy Object Storage authentication mechanism, you will need the follwing pieces of information:

Account ID: Your account username or ID. For HP Cloud customers, this is typically a long string of numbers and letters.
Key: Your secret key. For HP Customers, this is a string of random letters and numbers.
Endpoint URL: The URL given to you by your service provider.

HP Cloud users can find all of this information on your Object Storage account dashboard.

Parameters

string	$account	Your account name.
string	$key	Your secret key.
string	$url	The URL to the object storage endpoint.

Exceptions

HPCloud::Transport::AuthorizationException	if the authentication failed.
HPCloud::Transport::FileNotFoundException	if the URL is wrong.
HPCloud::Exception	if some other exception occurs.

Deprecated:: Newer versions of OpenStack use Keystone auth instead of Swift auth.

Definition at line 139 of file ObjectStorage.php.

References $account, $key, $store, ObjectStorage\$token, and ObjectStorage\$url.

Referenced by StreamWrapper\initializeObjectStorage().

req	(	$url,
		$method = `'GET'`,
		$jsonDecode = `TRUE`,
		$body = `''`
	)

protected

Internal request issuing command.

Definition at line 681 of file ObjectStorage.php.

References ObjectStorage\$url, and ObjectStorage\token().

Referenced by ObjectStorage\accountInfo(), ObjectStorage\container(), ObjectStorage\deleteContainer(), and ObjectStorage\get().

token ( )

Get the authentication token.

Return values

string

Returns: string The authentication token.

Definition at line 317 of file ObjectStorage.php.

References ObjectStorage\$token.

Referenced by ObjectStorage\__construct(), Container\__construct(), ObjectStorage\container(), ObjectStorage\containers(), Container\copy(), ObjectStorage\createContainer(), Container\delete(), RemoteObject\fetchObject(), Container\loadExtraData(), Container\objectQuery(), Container\proxyObject(), ObjectStorage\req(), Container\save(), and StreamWrapper\serviceCatalog().

updateContainer	(		$name,
		ACL	$acl = `NULL`,
			$metadata = `array()`
	)

Alias of createContainer().

At present, there is no distinction in the Swift REST API between creating an updating a container. In the future this may change, so you are encouraged to use this alias in cases where you clearly intend to update an existing container.

Definition at line 559 of file ObjectStorage.php.

References $name, and ObjectStorage\createContainer().

url ( )

Get the URL endpoint.

Return values

string

Returns: string The URL that is the endpoint for this service.

Definition at line 328 of file ObjectStorage.php.

References ObjectStorage\$url.

Referenced by ObjectStorage\__construct(), Container\__construct(), ObjectStorage\accountInfo(), ObjectStorage\container(), ObjectStorage\containers(), Container\copy(), ObjectStorage\createContainer(), Container\delete(), ObjectStorage\deleteContainer(), RemoteObject\fetchObject(), Container\loadExtraData(), Container\object(), Container\objectQuery(), Container\proxyObject(), Container\save(), and Container\updateMetadata().

useCDN ( $cdn )

Indicate that this ObjectStorage instance should use the given CDN service.

This will cause this ObjectStorage instance to use CDN as often as it can. Any containers (and subsequently container objects) that can leverage CDN services will act accordingly.

CDN is used for read operations. Because CDN is a time-based cache, objects in CDN can be older than objects in Swift itself. For that reason, CDN should not be used when a combination of read and write operations occur.

Return values

HPCloud::Storage::ObjectStorage

Returns: $this for current object so the method can be used in chaining.

Definition at line 257 of file ObjectStorage.php.

Member Data Documentation

$cdnContainers

protected

CDN containers.

This is an associative array of container names to URLs.

Definition at line 97 of file ObjectStorage.php.

$token = NULL

protected

The authorization token.

Definition at line 86 of file ObjectStorage.php.

Referenced by Container\__construct(), StreamWrapper\authenticate(), StreamWrapper\initializeCDN(), StreamWrapper\initializeObjectStorage(), RemoteObject\newFromHeaders(), RemoteObject\newFromJSON(), Container\newFromJSON(), Container\newFromResponse(), ObjectStorage\newFromSwiftAuth(), Container\object(), Container\save(), StreamWrapper\stream_open(), ObjectStorage\token(), StreamWrapper\unlink(), Container\updateMetadata(), and StreamWrapper\url_stat().

$url = NULL

protected

The URL to the Swift endpoint.

Definition at line 90 of file ObjectStorage.php.

Referenced by ObjectStorage\__construct(), Container\__construct(), ObjectStorage\accountInfo(), ObjectStorage\container(), ObjectStorage\containers(), ObjectStorage\createContainer(), Container\delete(), ObjectStorage\deleteContainer(), StreamWrapper\dir_opendir(), ObjectStorage\get(), RemoteObject\newFromHeaders(), RemoteObject\newFromJSON(), Container\newFromJSON(), Container\newFromResponse(), ObjectStorage\newFromSwiftAuth(), Container\object(), Container\objectQuery(), StreamWrapper\parseUrl(), Container\proxyObject(), ObjectStorage\req(), Container\save(), StreamWrapper\stream_open(), StreamWrapperFS\testDirectoryExists(), StreamWrapper\unlink(), Container\updateMetadata(), RemoteObject\url(), ObjectStorage\url(), Container\url(), StreamWrapper\url_stat(), RemoteObject\useCDN(), and Container\useCDN().

const API_VERSION = '1'

Definition at line 79 of file ObjectStorage.php.

const DEFAULT_REGION = 'region-a.geo-1'

Definition at line 81 of file ObjectStorage.php.

const SERVICE_TYPE = 'object-store'

The name of this service type in HPCloud.

This is used with IdentityService::serviceCatalog().

Definition at line 77 of file ObjectStorage.php.

The documentation for this class was generated from the following file:

src/HPCloud/Storage/ObjectStorage.php

Public Member Functions

Static Public Member Functions

Public Attributes

Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation