Encapsulador de flujo de Amazon S3 conAWS SDK for PHPVersión 3 - AWS SDK for PHP

Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

Encapsulador de flujo de Amazon S3 conAWS SDK for PHPVersión 3

El encapsulador de flujo de Amazon S3 le permite almacenar y recuperar datos de Amazon S3 utilizando funciones de PHP integradas comofile_get_contents,fopen,copy,rename,unlink,mkdir, yrmdir.

Debe registrar el encapsulador de flujo de Amazon S3 para utilizarlo.

$client = new Aws\S3\S3Client([/** options **/]); // Register the stream wrapper from an S3Client object $client->registerStreamWrapper();

De este modo, puede acceder a los buckets y objetos almacenados en Amazon S3 utilizando els3://Protocolo. El encapsulador de flujo de Amazon S3 acepta cadenas que contienen un nombre de bucket, seguido de una barra inclinada y una clave de objeto opcional o el prefijo:s3://<bucket>[/<key-or-prefix>].

nota

El encapsulador de flujo se ha diseñado para trabajar con objetos y buckets en los que tenga al menos permiso de lectura. Esto significa que su usuario debe tener permiso para ejecutar ListBucket en cualquier bucket y GetObject en cualquier objeto con el que el usuario necesita interactuar. Para los casos de uso en los que no tiene este nivel de permiso, le recomendamos que utilice las operaciones de cliente de Amazon S3 directamente.

Descargar datos

Puede tomar el contenido de un objeto utilizando file_get_contents. Sin embargo, tenga cuidado con esta función pues carga todo el contenido del objeto en la memoria.

// Download the body of the "key" object in the "bucket" bucket $data = file_get_contents('s3://bucket/key');

Usarfopen()cuando trabaje con archivos grandes o si necesita transmitir datos desde Amazon S3.

// Open a stream in read-only mode if ($stream = fopen('s3://bucket/key', 'r')) { // While the stream is still open while (!feof($stream)) { // Read 1,024 bytes from the stream echo fread($stream, 1024); } // Be sure to close the stream resource when you're done with it fclose($stream); }
nota

Los errores de escritura de archivos solo se devuelven cuando se llama a fflush. Esos errores no se devuelven cuando se llama a un fclose sin vaciar. El valor de retorno de fclose será true si cierra el flujo, sin importar si hay errores en respuesta a su fflush interno. Estos errores tampoco se devuelven al llamar a file_put_contents debido a cómo lo implementa PHP.

Abrir flujos rastreables

Los flujos abiertos en modo "r" solo admiten datos que se pueden leer desde el flujo y no se pueden rastrear de forma predeterminada. De este modo, los datos se pueden descargar desde Amazon S3 de forma de flujo real, donde los bytes leídos previamente no tengan que almacenarse en la memoria del búfer. Si necesita poder rastrear un flujo, puede transferir seekable a las opciones de contexto del flujo de una función.

$context = stream_context_create([ 's3' => ['seekable' => true] ]); if ($stream = fopen('s3://bucket/key', 'r', false, $context)) { // Read bytes from the stream fread($stream, 1024); // Seek back to the beginning of the stream fseek($stream, 0); // Read the same bytes that were previously read fread($stream, 1024); fclose($stream); }

La apertura de flujos rastreables le permite buscar bytes leídos previamente. No se puede pasar directamente a bytes que todavía no se han leído desde el servidor remoto. Para poder volver a llamar los datos leídos previamente, estos se almacenan en el búfer en un flujo de PHP temporal mediante un decorador de flujos. Cuando la cantidad de datos almacenados en la memoria caché supera los 2 MB, los datos del flujo temporal se transfieren de la memoria al disco. Tenga en mente esta posibilidad al descargar archivos grandes desde Amazon S3 utilizando elseekableconfiguración de contexto de flujo.

Cargar datos

Puede cargar datos a Amazon S3 mediantefile_put_contents().

file_put_contents('s3://bucket/key', 'Hello!');

Puede cargar archivos de mayor tamaño realizando un streaming de los datos utilizando fopen() y un modo de acceso de flujo "w", "x" o "a". El envoltorio de flujos de Amazon S3 lo hacenoadmite flujo de lectura y escritura simultánea (por ejemplo, «r+», «w+», etc.). Esto se debe a que el protocolo HTTP no permite la lectura y escritura simultáneas.

$stream = fopen('s3://bucket/key', 'w'); fwrite($stream, 'Hello!'); fclose($stream);
nota

Amazon S3 requiere que se especifique un encabezado de longitud del contenido antes de que se envíe la carga de una solicitud. Por ello, los datos que se cargan en una operación PutObject se almacenan internamente en el búfer mediante un flujo temporal de PHP hasta que se vacía o cierra el flujo.

nota

Los errores de escritura de archivos solo se devuelven cuando se llama a fflush. Esos errores no se devuelven cuando se llama a un fclose sin vaciar. El valor de retorno de fclose será true si cierra el flujo, sin importar si hay errores en respuesta a su fflush interno. Estos errores tampoco se devuelven al llamar a file_put_contents debido a cómo lo implementa PHP.

Modos fopen

La función fopen() de PHP requiere que especifique una opción $mode. La opción de modo especifica si se pueden leer o escribir datos en un flujo y si el archivo debe existir al abrir un flujo. El encapsulador de flujo de Amazon S3 admite los siguientes modos.

r

Es un flujo de solo lectura donde el archivo ya debe existir.

w

Es un flujo de solo escritura. Si el archivo ya existe, se sobrescribe.

a

Es un flujo de solo escritura. Si el archivo ya existe, se descarga en un flujo temporal y cualquier escritura en el flujo se agrega a cualquier dato cargado previamente.

x

Es un flujo de solo escritura. Aparece un error si el archivo no existe todavía.

Otras funciones de objeto

Los encapsuladores de flujo permiten que diferentes funciones de PHP integradas trabajen con un sistema personalizado como Amazon S3. Estas son algunas de las funciones que el encapsulador de flujo de Amazon S3 le permite realizar con objetos almacenados en Amazon S3.

unlink()

Elimina un objeto de un bucket.

// Delete an object from a bucket unlink('s3://bucket/key');

Puede transferir cualquiera de las opciones disponibles a la operación DeleteObject para modificar la forma en que se elimina el objeto (por ejemplo, especificando una versión del objeto determinada).

// Delete a specific version of an object from a bucket unlink('s3://bucket/key', stream_context_create([ 's3' => ['VersionId' => '123'] ]);

filesize()

Obtiene el tamaño de un objeto.

// Get the Content-Length of an object $size = filesize('s3://bucket/key', );

is_file()

Comprueba si una URL es un archivo.

if (is_file('s3://bucket/key')) { echo 'It is a file!'; }

file_exists()

Comprueba si existe un objeto.

if (file_exists('s3://bucket/key')) { echo 'It exists!'; }

filetype()

Comprueba si una URL se mapea con un archivo o bucket (dir).

file()

Carga el contenido de un objeto en una matriz de líneas. Puede transferir cualquiera de las opciones disponibles a la operación GetObject para modificar la forma en que se descarga el archivo.

filemtime()

Obtiene la última fecha de modificación de un objeto.

rename()

Para cambiar el nombre de un objeto copiándolo y eliminando el original. Puede transferir las opciones disponibles de las operaciones CopyObject y DeleteObject a los parámetros de contexto del flujo para modificar la forma en que se copia y elimina el objeto.

nota

Aunquecopynormalmente trabaja con el encapsulador de flujo de Amazon S3, es posible que algunos errores no se notifiquen correctamente debido a aspectos internos delcopyfunción en PHP. Le recomendamos que utilice una instancia de AwsS3ObjectCopier en su lugar.

Uso de buckets de

Puede modificar y examinar buckets de Amazon S3 de forma similar a cómo PHP permite la modificación y el recorrido de los directorios en su sistema de archivos.

A continuación se incluye un ejemplo de creación de un bucket.

mkdir('s3://bucket');

Puede transferir las opciones de contexto del flujo al método mkdir() para modificar la manera en que se crea el bucket utilizando los parámetros disponibles en la operación CreateBucket.

// Create a bucket in the EU (Ireland) Region mkdir('s3://bucket', stream_context_create([ 's3' => ['LocationConstraint' => 'eu-west-1'] ]);

Puede eliminar buckets utilizando la función rmdir().

// Delete a bucket rmdir('s3://bucket');
nota

Los buckets solo se pueden eliminar si están vacíos.

Mostrar el contenido de un bucket

Puede utilizar elopendir (),readdir (),rewinddir (), yclosedir ()PHP funciona con el contenedor de flujos de Amazon S3 para recorrer el contenido de un bucket. Puede transferir los parámetros disponibles para la operación ListObjects como opciones de contexto de flujo personalizadas a la función opendir() para modificar la forma en que se enumeran los objetos.

$dir = "s3://bucket/"; if (is_dir($dir) && ($dh = opendir($dir))) { while (($file = readdir($dh)) !== false) { echo "filename: {$file} : filetype: " . filetype($dir . $file) . "\n"; } closedir($dh); }

Puede crear una lista recursiva de cada objeto y prefijo en un bucket utilizando RecursiveDirectoryIterator de PHP.

$dir = 's3://bucket'; $iterator = new RecursiveIteratorIterator(new RecursiveDirectoryIterator($dir)); foreach ($iterator as $file) { echo $file->getType() . ': ' . $file . "\n"; }

Otra forma de enumerar el contenido de un bucket de forma recursiva que requiera menos solicitudes HTTP es utilizar la función Aws\recursive_dir_iterator($path, $context = null).

<?php require 'vendor/autoload.php'; $iter = Aws\recursive_dir_iterator('s3://bucket/key'); foreach ($iter as $filename) { echo $filename . "\n"; }

Opciones de contexto del flujo

Puede personalizar el cliente utilizado por el encapsulador de flujo o la caché utilizada para grabar en caché la información cargada previamente acerca de buckets y claves, transfiriendo las opciones de contexto del flujo personalizadas.

El encapsulador de flujo es compatible con las siguientes opciones de contexto del flujo en cada operación.

client

Es el objeto Aws\AwsClientInterface que se va a utilizar para ejecutar comandos.

cache

Es una instancia de Aws\CacheInterface que se va a utilizar para almacenar en caché las estadísticas de archivos obtenidas previamente. De forma predeterminada, el encapsulador de flujo utiliza una caché LRU en memoria.