StorageService Adapters

The interface Zend_Cloud_StorageService_Adapter defines methods that each concrete storage service adapter must implement. The following adapters are shipped with the Simple Cloud API:

» Zend_Cloud_StorageService_Adapter_S3
» Zend_Cloud_StorageService_Adapter_WindowsAzure
Zend_Cloud_StorageService_Adapter_FileSystem

To create the service object, call the static method Zend_Cloud_StorageService_Factory::getAdapter(), which accepts either an array or a Zend_Config object. The key named storage_adapter should specify the concrete adapter class. Adapter-specific keys may also be passed in this configuration parameter.

Example #1 Using the StorageService Factory

span style="color: #ff0000;">'Zend_Cloud_StorageService_Adapter_S3'

StorageService Adapter Options

**Zend_Cloud_StorageService_Adapter_S3 options**
Option key	Description	Used in	Required	Default
aws_accesskey	Amazon AWS access key	Constructor	Yes	None
aws_secretkey	Amazon AWS secret key	Constructor	Yes	None
bucket_name	The name of the S3 bucket for this item	Used in the constructor to set the default bucket for the instantiated service. This option can also be specified in any of the item access operations.	Yes	None
bucket_as_domain	Indicates that the bucket name is part of the domain name	Used in constructor to set the default behavior for the instantiated service. This option can also be specified in any of the item access operations.	No	False
metadata	Array of metadata to associate with the item	storeItem()	No	None
fetch_stream	Indicates whether the response is stream, and not a string Note: See the Zend_Service_Amazon_S3 documentation for more about handling streamed responses)	fetchItem()	No	False
http_adapter	HTTP adapter to use in all access operations	Constructor	No	Zend_Http_Client_Adapter_Socket

**Zend_Cloud_StorageService_Adapter_WindowsAzure options**
Option key	Description	Used in	Required	Default
storage_accountname	Windows Azure account name	Constructor	Yes	None
storage_accountkey	Windows Azure account key	Constructor	Yes	None
storage_container	Container to use for this storage object	Constructor	Yes	None
storage_host	Windows Azure access host	Constructor	Yes	`blob.core.windows.net`
storage_proxy_host	Proxy hostname	Constructor	No	None
storage_proxy_port	Proxy port	Constructor	No	8080
storage_proxy_credentials	Proxy credentials	Constructor	No	None
http_adapter	HTTP adapter to use in all access operations	Constructor	No	Zend_Http_Client_Adapter_Socket
returntype	How to return the results. For fetchItem(): `RETURN_STRING` Return the data as strings. `RETURN_PATH` save data on disk in temp file, return path name `RETURN_STREAM` Default: Return the data as stream For listItems(): `RETURN_NAMES` return the list of item names (default) `RETURN_LIST` return the list of WindowsAzure objects	fetchItem(), listItems()	No	`RETURN_STREAM` for fetchItem(); `RETURN_NAMES` for listItems()
return_path	Return path. This is the URL that can be used to access the item after it has been uploaded.	fetchItem()	No	System tmp directory
return_openmode	fopen() mode used to open the file for saving data	fetchItem()	No	'r'

**Zend_Cloud_StorageService_Adapter_Filesystem options**
Option key	Description	Used in	Required	Default
local_directory	Local directory where the files will be stored	Constructor	No	System tmp directory

Basic concepts

Different cloud storage services use their own unique terminology to refer to document storage concepts. The SimpleCloud API defines a number of common concepts that are shared among all major providers.

The storage service identifies files by string keys, which may be URL paths or another service-specific identifier. The items can be stored and retrieved using this key. Each item can have metadata associated with it. These metadata carry service-specific information about the item, such as size, type, permissions, etc. as defined in the adapter for that provider.

Exceptions

If some error occurs inside the storage service, a Zend_Cloud_StorageService_Exception is thrown. If the exception was caused by underlying service driver, you can use the getClientException() method to retrieve the original exception.

Since different cloud providers implement different sets of services, some adapters do not implement certain features. In this case, the Zend_Cloud_OperationNotAvailableException exception is thrown.

Store an item

storeItem() method is used to upload or otherwise add files to the storage provider.

Example #2 Storing an item

span style="color: #ff0000;">'/my/local/dir/picture.jpg''/my/remote/path/picture.jpg', $data);

An optional third parameter describes service-specific options.

Example #3 Storing an item with options

span style="color: #ff0000;">"/my/local/dir/picture.jpg");
 
// Use S3 bucket: myBucket
// Make this item publicly readable
'/my/remote/path/picture.jpg'"myBucket"

For service adapters that support streaming, data can also be a PHP stream (i.e. opened file).

Fetch an item

The fetchItem() operation retrieves an item from the storage.

Example #4 Fetching an item

span style="color: #ff0000;">"/my/remote/path/picture.jpg"

Delete an item

The deleteItem() operation removes an item from the storage service.

Example #5 Deleting an item

$storage->deleteItem("/my/remote/path/picture.jpg");

Copy an item

The copyItem() operation creates a copy of the item in the storage.

Note: Not all services support copying natively. If this is the case, the adapter will simulate the operation, fetching the item and storing it under the target path.

Example #6 Copying an item

span style="color: #ff0000;">'/my/remote/path/picture.jpg',
    '/anothor/remote/dir/picturecopy.jpg'
);

Move an item

The moveItem() operation moves an item from one key (or directory) to another.

Note: Not all services support moving natively. If this is the case the adapter will simulate the operation, fetching the item, storing it under the target path, then deleting the original file.

Example #7 Moving an item

$storage->moveItem(
    '/my/remote/path/picture.jpg',
    '/anothor/remote/dir/newpicture.jpg'
);

Rename an item

The renameItem() operation changes the item name. For some services, this operation may be equivalent to moving to its original directory with a new name.

Example #8 Renaming an item

span style="color: #ff0000;">'/my/remote/path/picture.jpg', 'newpicture.jpg');

List items

To list the items stored in the specified path, use the listItems() method. The method returns a list of names identifying matching remote items.

Example #9 List items

span style="color: #ff0000;">'/my/remote/path/'"Found: $objname\n";
}

Fetching metadata

Some services store a set of key-value pairs along with the item as metadata. Use the fetchMetadata() method to retrieve an item's metadata.

Example #10 Fetching metadata

$data = $storage->fetchMetadata('/my/remote/path/picture.jpg'"Metadata $key: $value\n";
}

Store metadata

Depending on the service, metadata can be supplied either when storing the item or with a separate request. In the latter case, use storeMetadata() to add or update this metadata.

Example #11 Storing metadata

$data = $storage->storeMetadata('/my/remote/path/picture.jpg''type'     => 'JPEG',
    'category' => 'Portrait',
));

Delete metadata

The deleteMetadata() method removes all user-supplied metadata from an item.

Note: Not all services support removing metadata.

Example #12 Deleting metadata

$storage->deleteMetadata("/my/remote/path/picture.jpg");

Accessing concrete adapters

Sometimes it is necessary to retrieve the concrete adapter for the service that the Storage API is working with. This can be achieved by using the getAdapter() method.

Note: Accessing the underlying adapter breaks portability among services, so it should be reserved for exceptional circumstances only.

Example #13 Using a concrete adapter

// the Simple Cloud Storage API doesn't support "clean bucket" operation
// the concrete adapter can be used to access this feature
$s3 = $storage->getClient();
$s3->cleanBucket("oldBucket");

StorageService Introduction