Zend_Service_Rackspace
Zend_Service
Programmer's Reference Guide

Zend_Service_Rackspace_Files

Overview

The Zend_Service_Rackspace_Files is a class that provides a simple API to manage the » Rackspace Cloud Files.

Quick Start

To use this class you have to pass the username and the API's key of Rackspace in the construction of the class.

  1. $user = 'username';
  2. $key  = 'secret key';
  3.  
  4. $rackspace = new Zend_Service_Rackspace_Files($user,$key);

A container is a storage compartment for your data and provides a way for you to organize your data. You can think of a container as a folder in Windows® or a directory in UNIX®. The primary difference between a container and these other file system concepts is that containers cannot be nested. You can, however, create an unlimited number of containers within your account. Data must be stored in a container so you must have at least one container defined in your account prior to uploading data.

The only restrictions on container names is that they cannot contain a forward slash (/) and must be less than 256 bytes in length (please note that the length restriction applies to the name using the URL encoded format).

The containers are managed using the class Zend_Service_Rackspace_Files_Container.

An object (file) is the basic storage entity and any optional metadata that represents the files you store in the Cloud Files system. When you upload data to Cloud Files, the data is stored as-is (no compression or encryption) and consists of a location (container), the object's name, and any metadata consisting of key/value pairs. For instance, you may chose to store a backup of your digital photos and organize them into albums. In this case, each object could be tagged with metadata such as Album : Caribbean Cruise or Album : Aspen Ski Trip.

The only restriction on object names is that they must be less than 1024 bytes in length after URL encoding. Cloud Files has a limit on the size of a single uploaded object; by default this is 5 GB. For metadata, you should not exceed 90 individual key/value pairs for any one object and the total byte length of all key/value pairs should not exceed 4KB (4096 bytes).

The objects are managed using the class Zend_Service_Rackspace_Files_Object.

To create a new container you can use the createContainer method.

  1. $container= $rackspace->createContainer('test');
  2.  
  3. if (!$rackspace->isSuccessful()) {
  4.     die('ERROR: '.$rackspace->getErrorMsg());
  5. }
  6.  
  7. printf("Name: %s",$container->getName());

This example create a container with name test. The result of createContainer is a new instance of Zend_Service_Rackspace_Files_Container.

To store an object (file) in a container you can use the storeObject method.

  1. $name= 'example.jpg';
  2. $file= file_get_contents($name);
  3.  
  4. $metadata= array (
  5.     'foo' => 'bar'
  6. );
  7.  
  8. $rackspace->storeObject('test',$name,$file,$metadata);
  9.  
  10. if ($rackspace->isSuccessful()) {
  11.     echo 'Object stored successfully';
  12. } else {
  13.     printf("ERROR: %s",$rackspace->getErrorMsg());
  14. }

This example store a file image example.jpg in the container test with the metadata specified in the array $metadata.

To delete an object (file) you can use the deleteObject method.

  1. $rackspace->deleteObject('test','example.jpg');
  2.  
  3. if ($rackspace->isSuccessful()) {
  4.     echo 'Object deleted successfully';
  5. } else {
  6.     printf("ERROR: %s",$rackspace->getErrorMsg());
  7. }

This example delete the object example.jpg in the container test.

To publish a container as CDN (Content Delivery Network) you can use the enableCdnContainer method.

  1. $cdnInfo= $rackspace->enableCdnContainer('test');
  2.  
  3. if ($rackspace->isSuccessful()) {
  4.     print_r($cdnInfo);
  5. } else {
  6.     printf("ERROR: %s",$rackspace->getErrorMsg());
  7. }

This example publish the container test as CDN. If the operation is successfull returns an associative arrays with the following values:

  • cdn_uri, the url of the CDN container;

  • cdn_uri_ssl, the ssl url of the CDN container;

Available Methods

copyObject ( string $container_source,string $obj_source,string $container_dest,string $obj_dest,$metadata=array(),string $content_type=null )

Copy an object from a container to another. The return is true in case of success and false in case of error.

The $container_source is the name of the source container.

The $obj_source is the name of the source object.

The $container_dest is the name of the destination container.

The $obj_dest is the name of the destination object.

The $metadata array contains the metadata information related to the destination object.

The $content_type is the optional content type of the destination object (file).

createContainer ( string $container, $metadata=array() )

Create a container. The return is an instance of Zend_Service_Rackspace_Files_Container. In case of error the return is false.

The $container is the name of the container to create.

The $metadata array contains the metadata information related to the container.

deleteContainer ( string $container )

Delete a container. The return is true in case of success and false in case of error.

The $container is the name of the container to delete.

deleteObject ( string $container,string $object )

Delete an object in a specific container. Return true in case of success, false in case of error.

The $container is the name of the container.

The $object is the name of the object to delete.

enableCdnContainer ( string $container,integer $ttl=900 )

Publish a container as CDN (Content Delivery Network). Return an associative array contains the CDN url and SSL url. In case of error the return is false.

The $container is the name of the container.

The $ttl is the time to live for the CDN cache content. The default value is 15 minutes (900 seconds). The minimum TTL that can be set is 15 minutes (900 seconds); the maximum TTL is 50 years (range of 900 to 1577836800 seconds).

getCdnContainers ( $options=array() )

Returns all the CDN containers available. The return is an instance of Zend_Service_Rackspace_Files_ContainerList. In case of error the return is false.

The $options contains the following optional parameters:

  • limit, for an integer value n, limits the number of results to at most n values.

  • marker, given a string value x, return object names greater in value than the specified marker.

getContainers ( $options=array() )

Returns all the containers available. The return is an instance of Zend_Service_Rackspace_Files_ContainerList In case of error the return is false.

The $options contains the following optional parameters:

  • limit, for an integer value n, limits the number of results to at most n values.

  • marker, given a string value x, return object names greater in value than the specified marker.

getContainer ( string $container )

Returns the container specified as instance of Zend_Service_Rackspace_Files_Container In case of error the return is false.

The $container is the name of the container.

getCountContainers ( )

Return the total count of containers.

getCountObjects ( )

Return the count of objects contained in all the containers.

getInfoCdnContainer ( string $container )

Get the information of a CDN container. The result is an associative array with all the CDN information. In case of error the return is false.

The $container is the name of the container.

getInfoContainers ( )

Get the information about all the containers available. Return an associative array with the following values:

  • tot_containers, the total number of containers stored

  • size_containers, the total size, in byte, of all the containers.

  • tot_objects, the total number of objects (file) stored in all the containers.

In case of error the return is false.

getMetadataContainer ( string $container )

Get the metadata information of a container. The result is an associative array with all the metadata keys/values. In case of error the return is false.

The $container is the name of the container.

getMetadataObject ( string $container, string $object )

Get the metadata information of an object. The result is an associative array with all the metadata keys/values. In case of error the return is false.

The $container is the name of the container.

The $object is the name of the object.

getObjects ( string $container, $options=array() )

Returns all the objects of a container. The return is an instance of Zend_Service_Rackspace_Files_ObjectList In case of error the return is false.

The $container is the name of the container.

The $options contains the following optional parameters:

  • limit, for an integer value n, limits the number of results to at most n values.

  • marker, given a string value x, return object names greater in value than the specified marker.

  • prefix, for a string value x, causes the results to be limited to object names beginning with the substring x.

  • path, for a string value x, return the object names nested in the pseudo path.

  • delimiter, for a character c, return all the object names nested in the container (without the need for the directory marker objects).

getObject ( string $container, string $object, $headers=array() )

Returns an object of a container. The return is an instance of Zend_Service_Rackspace_Files_Object In case of error the return is false.

The $container is the name of the container.

The $object is the name of the object.

The $headers contains the following optional parameters (See the » RFC-2616 for more info):

  • If-Match, a client that has one or more entities previously obtained from the resource can verify that one of those entities is current by including a list of their associated entity tags in the If-Match header field.

  • If-None-Match, a client that has one or more entities previously obtained from the resource can verify that none of those entities is current by including a list of their associated entity tags in the If-None-Match header field.

  • If-Modified-Since, if the requested variant has not been modified since the time specified in this field, an entity will not be returned from the server.

  • If-Unmodified-Since, if the requested resource has not been modified since the time specified in this field, the server SHOULD perform the requested operation as if the If-Unmodified-Since header were not present.

  • Range, Rackspace supports a sub-set of Range and do not adhere to the full RFC-2616 specification. We support specifying OFFSET-LENGTH where either OFFSET or LENGTH can be optional (not both at the same time). The following are supported forms of the header:

    • Range: bytes=-5, last five bytes of the object

    • Range: bytes=10-15, the five bytes after a 10-byte offset

    • Range: bytes=32-, all data after the first 32 bytes of the object

getSizeContainers ( )

Return the size, in bytes, of all the containers.

setMetadataObject ( string $container,string $object, array $metadata )

Update metadata information to the object (all the previous metadata will be deleted). Return true in case of success, false in case of error.

The $container is the name of the container.

The $object is the name of the object to store.

The $metadata array contains the metadata information related to the object.

storeObject ( string $container,string $object,string $file,$metadata=array() )

Store an object in a specific container. Return true in case of success, false in case of error.

The $container is the name of the container.

The $object is the name of the object to store.

The $file is the content of the object to store.

The $metadata array contains the metadata information related to the object to store.

updateCdnContainer ( string $container,integer $ttl=null,$cdn_enabled=null,$log=null )

Update the attribute of a CDN container. Return an associative array contains the CDN url and SSL url. In case of error the return is false.

The $container is the name of the container.

The $ttl is the time to live for the CDN cache content. The default value is 15 minutes (900 seconds). The minimum TTL that can be set is 15 minutes (900 seconds); the maximum TTL is 50 years (range of 900 to 1577836800 seconds).

The $cdn_enabled is the flag to swith on/off the CDN. True switch on, false switch off.

The $log enable or disable the log retention. True switch on, false switch off.

Examples

Example #1 Authenticate

Check if the username and the key are valid for the Rackspace authentication.

  1. $user = 'username';
  2. $key  = 'secret key';
  3.  
  4. $rackspace = new Zend_Service_Rackspace_Files($user,$key);
  5.  
  6. if ($rackspace->authenticate()) {
  7.     printf("Authenticated with token: %s",$rackspace->getToken());
  8. } else {
  9.     printf("ERROR: %s",$rackspace->getErrorMsg());
  10. }

Example #2 Get an object

Get an image file (example.gif) from the cloud and render it in the browser

  1. $user = 'username';
  2. $key  = 'secret key';
  3.  
  4. $rackspace = new Zend_Service_Rackspace_Files($user,$key);
  5.  
  6. $object= $rackspace->getObject('test','example.gif');
  7.  
  8. if (!$rackspace->isSuccessful()) {
  9.     die('ERROR: '.$rackspace->getErrorMsg());
  10. }
  11.  
  12. header('Content-type: image/gif');
  13. echo $object->getFile();

Example #3 Create a container with metadata

Create a container (test) with some metadata information ($metadata)

  1. $user = 'username';
  2. $key  = 'secret key';
  3.  
  4. $rackspace = new Zend_Service_Rackspace_Files($user,$key);
  5.  
  6. $metadata= array (
  7.     'foo'  => 'bar',
  8.     'foo2' => 'bar2',
  9. );
  10.  
  11. $container= $rackspace->createContainer('test',$metadata);
  12.  
  13. if ($rackspace->isSuccessful()) {
  14.     echo 'Container created successfully';
  15. }

Example #4 Get the metadata of a container

Get the metadata of the container test

  1. $user = 'username';
  2. $key  = 'secret key';
  3.  
  4. $rackspace = new Zend_Service_Rackspace_Files($user, $key);
  5.  
  6. $container= $rackspace->getContainer('test');
  7.  
  8. if (!$rackspace->isSuccessful()) {
  9.     die('ERROR: ' . $rackspace->getErrorMsg());
  10. }
  11.  
  12. $metadata= $container->getMetadata();
  13. print_r($metadata);

Example #5 Store an object in a container

Store an object using a Zend_Service_Rackspace_Files_Container instance

  1. $user = 'username';
  2. $key  = 'secret key';
  3.  
  4. $rackspace = new Zend_Service_Rackspace_Files($user, $key);
  5.  
  6. $container= $rackspace->getContainer('test');
  7.  
  8. if (!$rackspace->isSuccessful()) {
  9.     die('ERROR: ' . $rackspace->getErrorMsg());
  10. }
  11.  
  12. $file     = file_get_contents('test.jpg');
  13. $metadata = array (
  14.     'foo' => 'bar',
  15. );
  16.  
  17. if ($container->addObject('test.jpg', $file, $metadata)) {
  18.     echo 'Object stored successfully';
  19. }

Example #6 Check if a container is CDN enabled

Check if the test container is CDN enabled. If it is not we enable it.

  1. $user = 'username';
  2. $key  = 'secret key';
  3.  
  4. $rackspace = new Zend_Service_Rackspace_Files($user, $key);
  5.  
  6. $container= $rackspace->getContainer('test');
  7.  
  8. if (!$rackspace->isSuccessful()) {
  9.     die('ERROR: ' . $rackspace->getErrorMsg());
  10. }
  11.  
  12. if (!$container->isCdnEnabled()) {
  13.     if (!$container->enableCdn()) {
  14.         die('ERROR: ' . $rackspace->getErrorMsg());
  15.     }
  16. }
  18.     "The container is CDN enabled with the following URLs:\n %s\n %s\n",
  19.     $container->getCdnUri(),
  20.     $container->getCdnUriSsl()
  21. );
Zend_Service_Rackspace
Zend_Service
Programmer's Reference Guide