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.

$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,
));

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.

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.

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

$data = file_get_contents('/my/local/dir/picture.jpg');
$returnedData = $storage->storeItem('/my/remote/path/picture.jpg', $data);

An optional third parameter describes service-specific options.

$data = file_get_contents("/my/local/dir/picture.jpg");

// Use S3 bucket: myBucket
// Make this item publicly readable
$returnedData = $storage->storeItem(
    '/my/remote/path/picture.jpg',
    $data,
    array(
        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).

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

$returnedData = $storage->fetchItem("/my/remote/path/picture.jpg");
file_put_contents($localFilePath, $returnedData);

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

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

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

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

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

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

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.

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

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";
}

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.

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

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.

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

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

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

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.

// 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");