StorageService Introduction
The storage service in the Simple Cloud API implements a basic interface for file storage on
the cloud. The files have no internal structure as far as the service is concerned, and are
identified by a string key that is analogous to a filepath on a filesystem.
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:
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
$storage = Zend_Cloud_StorageService_Factory::
getAdapter(array( Zend_Cloud_StorageService_Factory::STORAGE_ADAPTER_KEY => 'Zend_Cloud_StorageService_Adapter_S3',
Zend_Cloud_StorageService_Adapter_S3::AWS_ACCESS_KEY => $amazonKey,
Zend_Cloud_StorageService_Adapter_S3::AWS_SECRET_KEY => $amazonSecret,
));
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_Nirvanix options
| Option key |
Description |
Used in |
Required |
Default |
| auth_username |
Nirvanix user name |
Constructor |
Yes |
None |
| auth_password |
Nirvanix password |
Constructor |
Yes |
None |
| auth_accesskey |
Nirvanix access key |
Constructor |
Yes |
None |
| http_adapter |
HTTP adapter to use in all access operations |
Constructor |
No |
Zend_Http_Client_Adapter_Socket |
| remote_directory |
Nirvanix directory to use |
Constructor (mandatory) |
Yes |
None |
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
$returnedData = $storage->storeItem('/my/remote/path/picture.jpg', $data);
An optional third parameter describes service-specific options.
Example #3 Storing an item with options
// Use S3 bucket: myBucket
// Make this item publicly readable
$returnedData = $storage->storeItem(
'/my/remote/path/picture.jpg',
$data,
Zend_Cloud_StorageService_Adapter_S3::BUCKET_NAME => "myBucket",
Zend_Cloud_StorageService_Adapter_S3::
METADATA =>
array( Zend_Service_Amazon_S3::S3_ACL_HEADER => Zend_Service_Amazon_S3::S3_ACL_PUBLIC_READ,
)
)
);
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
$returnedData = $storage->fetchItem("/my/remote/path/picture.jpg");
file_put_contents($localFilePath, $returnedData);
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
$storage->copyItem(
'/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
$storage->renameItem('/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.
$objects = $storage->listItems('/my/remote/path/');
foreach ($objects as $objname) {
echo "Found: $objname\n";
}
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");