Provides CDN services for ObjectStorage. More...

Public Member Functions
	__construct ($token, $endpoint)
	Build a new CDN object.
	containers ($enabledOnly=NULL)
	Get a list of containers that the CDN system knows of.
	container ($name)
	Get a container by name.
	enable ($name, $ttl=NULL, &$created=FALSE)
	Enable a container.
	update ($name, $attrs)
	Set attributes on a CDN container.
	delete ($name)
	Attempt to remove a container from CDN.

Static Public Member Functions
static	newFromIdentity ($identity, $region=CDN::DEFAULT_REGION)
	Create a new instance from an IdentityServices object.
static	newFromServiceCatalog ($catalog, $token, $region=CDN::DEFAULT_REGION)
	Create a new CDN object based on a service catalog.

Public Attributes
const	SERVICE_TYPE = 'hpext:cdn'
	The name of the CDN service type.
const	API_VERSION = '1.0'
	The API version.
const	DEFAULT_REGION = 'region-a.geo-1'

Protected Member Functions
	modifyContainer ($name, $method, $headers=array(), $qstring= '')
	Run the given method on the given container.

Protected Attributes
	$url
	The URL to the CDN endpoint.
	$token
	The authentication/authorization token.

Detailed Description

Provides CDN services for ObjectStorage.

CDN stands for "Content Distribution Network." It provides distributed caching in the cloud. When a Container is CDN-enabled, objects will be stored not just in the ObjectStorage, but temporary cached copies will be stored on servers around the world.

Attention: Caches are not protected by authentication. If you store an object in a CDN, cached versions of that object are publically accessible. Setting an ACL will have very little impact on this.

CDN is an HPCloud extension service, and is not presently part of OpenStack proper. The current REST API documentation can be found at http://api-docs.hpcloud.com/

Usage

The CDN service functions as an add-on to ObjectStorage. It adds a caching layer. So terms used here, such as Container and Object, refer to the ObjectStorage items.

For the most part, CDN operates on the Container level. You can choose to tell the CDN about a particular Container in ObjectStorage, and it will cache items in that container.

The CDN service keeps a list of ObjectStorage Containers that it knows about. CDN does not automatically discover ObjectStorage Containers; you must tell CDN about the ObjectStorage instances you want it to know about. This is done using CDN::enable().

Once the CDN service knows about an ObjectStorage Container, it will begin caching objects in that container.

This library gives the the ability to do the following:

List the containers that CDN knows about: CDN::containers()
Retrieve the CDN properties for a particular Container: CDN::container().
Add and enable containers: CDN::enable().
Remove a Container from CDN: CDN::delete().
Modify the caching properties of a Container: CDN::update().
Temporarily enable or disable caching for a container with CDN::update().

Example

<?php
// Authentication info:
$endpoint = 'https://auth.example.com';
$username = 'butcher@hp.com';
$password = 'secret';
$tenantId = '123456789';
// First we need to authenticate:
$identity = new \HPCloud\Services\IdentityServices($endpoint);
$token = $identity->authenticateAsUser($username, $password, $tenantId);
// Get the service catalog. We will try to have CDN build itself from
// the service catalog.
$catalog = $identity->serviceCatalog();
// Get a new CDN instance:
$cdn = CDN::newFromServiceCatalog($catalog, $token);
// Add a container to CDN; set cache lifetime to an hour:
$cdn->enable('myContainer', 3600);
// Get a list of all containers that CDN knows about,
// and print cache lifetime for each:
foreach ($cdn->containers() as $container) {
  print $container['name'] . ':' . $container['ttl'] . PHP_EOL;
}
// Change the cache lifetime on our container
$cdn->update('myContainer', array('ttl' => 7200));
// Temporarily stop the container from caching:
$cdn->update('myContainer', array('cdn_enabled' => FALSE);
//This can be re-enabled again:
$cdn->update('myContainer', array('cdn_enabled' => TRUE);
// If we no longer want this Container in CDN, we
// should delete it, not just disable it:
$cdn->delete('myContainer');
?>

Definition at line 121 of file CDN.php.

Constructor & Destructor Documentation

__construct	(	$token,
		$endpoint
	)

Build a new CDN object.

This object facilitates communication with the CDN cloud service.

This creates a new CDN object that will view as its endpoint the server with the URL $endpoint, which has the form:

https://ENDPOINT/API_VERSION/ACCOUNT

On older SwiftAuth-based services, the token should be the swauth token. On newer releaes, the token is retrieved from IdentityServices.

Parameters

string	$endpoint	The URL of the CDN service. It should look something like this: `https://cdnmgmt.rndd.aw1.hpcloud.net/v1.0/72020596871800`
string	$token	The authentication token. This can be retrieved from IdentityServices::token().

Definition at line 256 of file CDN.php.

References $endpoint, and CDN\$token.

Member Function Documentation

container ( $name )

Get a container by name.

Todo:: The current (1.0) version does not support a verb for getting just one container, so we have to get the entire list of containers.

Example return value:

<?php
array(
  'log_retention' => 1
  'cdn_enabled' => 1
  'name' => 'I♡HPCloud'
  'x-cdn-uri' => 'http://hcf937838.cdn.aw1.hpcloud.net'
  'ttl' => 1234
);
?>

Parameters

string $name The name of the container to fetch.

Return values

array

Returns: array An associative array in the exact format as in containers.

Definition at line 370 of file CDN.php.

References $container, $name, and CDN\containers().

containers ( $enabledOnly = NULL )

Get a list of containers that the CDN system knows of.

This returns a list of ObjectStorage Containers that the CDN service knows of. These containers can be either enabled or disabled.

The CDN service does not attempt to discover all of the containers from a Swift endpoint. Instead, it passively acquires a list of containers (added via, for example, enabledContainer()).

Once a container has been added to the CDN service, it can be in one of two states:

enabled (cdn_enabled=TRUE)
disabled (cdn_enabled=FALSE)

This listing will retrieve both enabled and disabled unless $enabledOnly is set to TRUE.

Returned data is in this format:

<?php
array(
  array(
    'log_retention' => 0
    'cdn_enabled' => 1
    'name' => 'I♡HPCloud'
    'x-cdn-uri' => 'http://hcf937838.cdn.aw1.hpcloud.net'
    'x-cdn-ssl-uri' => 'https://hcf937838.cdn.aw1.hpcloud.net'
    'ttl' => 1234
  ),
  array(
    'log_retention' => 0
    'cdn_enabled' => 0
    'name' => 'HPCloud2'
    'x-cdn-uri' => 'http://hcf9abc38.cdn.aw1.hpcloud.net'
    'x-cdn-ssl-uri' => 'https://hcf937838.cdn.aw1.hpcloud.net'
    'ttl' => 1234
  ),
);
?>

Attention: The $enabledOnly flag sendes enabled_only to the endpoint. The endpoint may or may not honor this.

Parameters

boolean $enabledOnly If this is set to TRUE, then only containers that are CDN-enabled will be returned.

Return values

array

Returns: array An indexed array of associative arrays. The format of each associative array is explained on container().

Exceptions

HPCloud::Exception An HTTP-level exception on error.

Definition at line 320 of file CDN.php.

References CDN\$url.

Referenced by CDN\container().

delete ( $name )

Attempt to remove a container from CDN.

This will remove a container from CDN services, completely stopping all caching on that container.

Deleted containers will no longer show up in the containers() list, nor will they be accessible via container().

Deleted containers can be added back with enable().

Parameters

string $name The Container name.

Return values

boolean

Returns: boolean TRUE if the container was successfully deleted, FALSE if the container was not removed, but no error occurred.

Exceptions

HPCloud::Exception Any of the HTTP error subclasses can be thrown.

Definition at line 556 of file CDN.php.

References $name, and CDN\modifyContainer().

enable	(		$name,
			$ttl = `NULL`,
		&	$created = `FALSE`
	)

Enable a container.

This adds the container to the CDN service and turns on caching.

In the CDN API, there are two meanings for the term "enable":

To "CDN-enable" a container means to add that container to the CDN service. There is no "CDN-disable".
To "enable" a container means to cache that container's content in a publically available CDN server. There is also a way to "disable" in this sense – which blocks a container from caching.

This method does the first – it adds a container to the CDN service. It so happens that adding a container also enables (in the second sense) the container. (This is a feature of the remote service, not the API).

Enabling and disabling (in the second sense) are considered temporary operations to switch on and off caching on a particular container. Both of these operations are done with the update() method.

The endpoint is supposed to return different results based on the above; accordingly this method should return TRUE if the container was added to the list, and FALSE if it was already there. HOWEVER, in some versions of the CDN service the endpoint returns the same code for both operations, so the result cannot be relied upon.

Parameters

string	$name	The name of the container.
int	$ttl	Time to live. The number of seconds an object may stay in the cache. This is the maximum amount of time. There is, however, no assurance that the object will remain for the full TTL. 15 minutes is the minimum time. Five years is the max.
boolean	$created	If this is passed, then its value will be set to TRUE if the container was created in the CDN, or FALSE if the container already existed in CDN.

Return values

string

Returns: string TRUE if the container was created, FALSE if the container was already added to the CDN (and thus nothing happened).

Exceptions

HPCloud::Exception Several HTTP-level exceptions can be thrown.

See Also: http://api-docs.hpcloud.com/hpcloud-cdn-storage/1.0/content/cdn-enable-container.html

Definition at line 431 of file CDN.php.

References $name, CDN\$url, and CDN\modifyContainer().

modifyContainer	(	$name,
		$method,
		$headers = `array()`,
		$qstring = `''`
	)

protected

Run the given method on the given container.

Checks to see if the expected result is returned.

Parameters

string	$name	The name of the container.
string	$method	The appropriate HTTP verb.
int	$expects	The expected HTTP code.

Definition at line 573 of file CDN.php.

References $name, CDN\$token, and CDN\$url.

Referenced by CDN\delete(), CDN\enable(), and CDN\update().

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

static

Create a new instance from an IdentityServices object.

This builds a new CDN instance form an authenticated IdentityServices object.

In the service catalog, this selects the first service entry for CDN. At this time, that is sufficient.

Parameters

HPCloud::Services::IdentityServices $identity The identity to use.

Return values

boolean
HPCloud::Storage::CDN

Returns: |boolean A CDN object or FALSE if no CDN services could be found in the catalog.

Definition at line 160 of file CDN.php.

References CDN\newFromServiceCatalog().

static newFromServiceCatalog	(	$catalog,
		$token,
		$region = `CDN::DEFAULT_REGION`
	)

static

Create a new CDN object based on a service catalog.

The IdentityServices class contains a service catalog, which tracks all services that the present account can access. The service catalog contains data necessary to connect to a CDN endpoint. This builder simplifies the process of creating a new CDN by accepting a service catalog and discovering the CDN service automatically.

In the vast majority of cases, this is the easiest way to proceed. If, however, a service catalog has multiple CDN instances (a possibility, though not currently supported), the present method has no means of determining which should be used. It simply chooses the first CDN service endpoint.

This uses the tenant ID that is found in the service catalog.

Either of the following work:

<?php
// Use a full service catalog:
$fullCatalog = $identityService->serviceCatalog();
$cdn = CDN::newFromServiceCatalog($fullCatalog);
// Use a filtered service catalog:
$catalog = $identitySerice->serviceCatalog(CDN::SERVICE_TYPE);
$cdn = CDN::newFromServiceCatalog($catalog);
?>

Parameters

array	$catalog	A service catalog; see HPCloud::Services::IdentityServices::serviceCatalog().
string	$token	The token.

Return values

boolean
HPCloud::Storage::CDN

Returns: boolean| A CDN object or FALSE if no CDN services could be found in the catalog.

Definition at line 208 of file CDN.php.

References $catalog, $endpoint, and CDN\$token.

Referenced by CDN\newFromIdentity().

update	(	$name,
		$attrs
	)

Set attributes on a CDN container.

This updates the attributes (that is, properties) of a container.

The following attributes are supported:

'ttl': Time to life in seconds (int).
'cdn_enabled': Whether the CDN is enabled (boolean).
'log_retention': Whether logs are retained (boolean). UNSUPPORTED.

Future versions of the CDN service will likely provide other properties.

Parameters

string	$name	The name of the container.
array	$attrs	An associative array of attributes.

Return values

boolean

Returns: boolean TRUE if the update was successful.

Exceptions

HPCloud::Exception Possibly throws one of the HTTP exceptions.

Definition at line 467 of file CDN.php.

References $name, and CDN\modifyContainer().

Member Data Documentation

$token

protected

The authentication/authorization token.

Definition at line 141 of file CDN.php.

Referenced by CDN\__construct(), CDN\modifyContainer(), and CDN\newFromServiceCatalog().

$url

protected

The URL to the CDN endpoint.

Definition at line 137 of file CDN.php.

Referenced by CDN\containers(), CDN\enable(), and CDN\modifyContainer().

const API_VERSION = '1.0'

The API version.

Definition at line 130 of file CDN.php.

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

Definition at line 132 of file CDN.php.

const SERVICE_TYPE = 'hpext:cdn'

The name of the CDN service type.

Definition at line 126 of file CDN.php.

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

src/HPCloud/Storage/CDN.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