La interfaz Zend_Cloud_StorageService_Adapter define los métodos que cada adaptador concreto de servicio de almacenamiento debe implementar. Los siguientes adaptadores se distribuyen con la Simple Cloud API:

Para crear el objeto de servicio, llame al método estático Zend_Cloud_StorageService_Factory::getAdapter(), que acepta un array o un objeto Zend_Config. La clave llamada storage_adapter debe especificar la clase del adaptador concreto. También pueden pasarse en este parámetro de configuración claves específicas del adaptador.

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

19.3.1.1. Opciones del adaptador de StorageService

Tabla 19.7. Opciones de Zend_Cloud_StorageService_Adapter_S3

Clave de opción	Descripción	Usado en	Requerido	Por defecto
aws_accesskey	Clave de acceso de Amazon AWS	Constructor	Sí	Ninguno
aws_secretkey	Clave secreta de Amazon AWS	Constructor	Sí	Ninguno
bucket_name	El nombre del bucket de S3 para este elemento	Se usa en el constructor para establecer el bucket por defecto de la instancia del servicio. Esta opción también puede especificarse en cualquiera de las operaciones de acceso a elementos.	Sí	Ninguno
bucket_as_domain	Indica que el nombre del bucket forma parte del nombre de dominio	Se usa en el constructor para establecer el comportamiento por defecto de la instancia del servicio. Esta opción también puede especificarse en cualquiera de las operaciones de acceso a elementos.	No	False
metadata	Array de metadatos a asociar con el elemento	storeItem()	No	Ninguno
fetch_stream	Indica si la respuesta es un stream, y no una cadena Nota Consulte la documentación de Zend_Service_Amazon_S3 para más información sobre el manejo de respuestas en streaming)	fetchItem()	No	False
http_adapter	Adaptador HTTP a usar en todas las operaciones de acceso	Constructor	No	Zend_Http_Client_Adapter_Socket

Tabla 19.8. Opciones de Zend_Cloud_StorageService_Adapter_WindowsAzure

Clave de opción	Descripción	Usado en	Requerido	Por defecto
storage_accountname	Nombre de la cuenta de Windows Azure	Constructor	Sí	Ninguno
storage_accountkey	Clave de la cuenta de Windows Azure	Constructor	Sí	Ninguno
storage_container	Contenedor a usar para este objeto de almacenamiento	Constructor	Sí	Ninguno
storage_host	Host de acceso de Windows Azure	Constructor	Sí	blob.core.windows.net
storage_proxy_host	Nombre de host del proxy	Constructor	No	Ninguno
storage_proxy_port	Puerto del proxy	Constructor	No	8080
storage_proxy_credentials	Credenciales del proxy	Constructor	No	Ninguno
http_adapter	Adaptador HTTP a usar en todas las operaciones de acceso	Constructor	No	Zend_Http_Client_Adapter_Socket
returntype	Cómo devolver los resultados. Para fetchItem(): RETURN_STRING Devuelve los datos como cadenas. RETURN_PATH guarda los datos en disco en un archivo temporal, devuelve el nombre de la ruta RETURN_STREAM Por defecto: devuelve los datos como stream Para listItems(): RETURN_NAMES devuelve la lista de nombres de elementos (por defecto) RETURN_LIST devuelve la lista de objetos WindowsAzure	fetchItem(), listItems()	No	RETURN_STREAM para fetchItem(); RETURN_NAMES para listItems()
return_path	Ruta de retorno. Esta es la URL que puede usarse para acceder al elemento una vez que se ha subido.	fetchItem()	No	Directorio tmp del sistema
return_openmode	Modo de fopen() usado para abrir el archivo al guardar los datos	fetchItem()	No	'r'

Tabla 19.9. Opciones de Zend_Cloud_StorageService_Adapter_Filesystem

Clave de opción	Descripción	Usado en	Requerido	Por defecto
local_directory	Directorio local donde se almacenarán los archivos	Constructor	No	Directorio tmp del sistema

Los diferentes servicios de almacenamiento en la nube usan su propia terminología para referirse a los conceptos de almacenamiento de documentos. La SimpleCloud API define una serie de conceptos comunes compartidos entre todos los principales proveedores.

El servicio de almacenamiento identifica los archivos mediante claves de tipo cadena, que pueden ser rutas URL u otro identificador específico del servicio. Los elementos pueden almacenarse y recuperarse usando esta clave. Cada elemento puede tener metadatos asociados. Estos metadatos contienen información específica del servicio sobre el elemento, como el tamaño, el tipo, los permisos, etc., según lo definido en el adaptador de ese proveedor.

Si ocurre algún error dentro del servicio de almacenamiento, se lanza una Zend_Cloud_StorageService_Exception. Si la excepción fue causada por el controlador del servicio subyacente, puede usar el método getClientException() para recuperar la excepción original.

Dado que los diferentes proveedores de nube implementan distintos conjuntos de servicios, algunos adaptadores no implementan ciertas funcionalidades. En este caso, se lanza la excepción Zend_Cloud_OperationNotAvailableException.

El método storeItem() se usa para subir o añadir de otro modo archivos al proveedor de almacenamiento.

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

Un tercer parámetro opcional describe opciones específicas del servicio.

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

Para adaptadores de servicio que admiten streaming, los datos también pueden ser un stream de PHP (es decir, un archivo abierto).

La operación fetchItem() recupera un elemento del almacenamiento.

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

La operación deleteItem() elimina un elemento del servicio de almacenamiento.

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

La operación copyItem() crea una copia del elemento en el almacenamiento.

	Nota
	No todos los servicios admiten la copia de forma nativa. Si este es el caso, el adaptador simulará la operación, recuperando el elemento y almacenándolo en la ruta de destino.

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

La operación moveItem() mueve un elemento de una clave (o directorio) a otra.

	Nota
	No todos los servicios admiten mover de forma nativa. Si este es el caso, el adaptador simulará la operación, recuperando el elemento, almacenándolo en la ruta de destino y luego eliminando el archivo original.

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

La operación renameItem() cambia el nombre del elemento. En algunos servicios, esta operación puede ser equivalente a mover a su directorio original con un nuevo nombre.

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

Para listar los elementos almacenados en la ruta especificada, use el método listItems(). El método devuelve una lista de nombres que identifican los elementos remotos coincidentes.

$objects = $storage->listItems('/my/remote/path/');
foreach ($objects as $objname) {
    echo "Found: $objname\n";
}

Algunos servicios almacenan un conjunto de pares clave-valor junto con el elemento como metadatos. Use el método fetchMetadata() para recuperar los metadatos de un elemento.

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

Según el servicio, los metadatos pueden proporcionarse al almacenar el elemento o mediante una solicitud independiente. En este último caso, use storeMetadata() para añadir o actualizar estos metadatos.

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

El método deleteMetadata() elimina todos los metadatos proporcionados por el usuario de un elemento.

	Nota
	No todos los servicios admiten la eliminación de metadatos.

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

A veces es necesario recuperar el adaptador concreto del servicio con el que está trabajando la Storage API. Esto puede lograrse usando el método getAdapter().

	Nota
	Acceder al adaptador subyacente rompe la portabilidad entre servicios, por lo que debería reservarse solo para circunstancias excepcionales.

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