Encapsulador de flujo de Amazon S3 con la versión 3 de AWS SDK for PHP

El encapsulador de flujo de Amazon S3 le permite almacenar y recuperar datos de Amazon S3 utilizando funciones de PHP integradas como, por ejemplo, file_get_contents, fopen, copy, rename, unlink, mkdir y rmdir.

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 el protocolo s3://. 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>].

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');

Utilice fopen() 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);
}

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. Esto es así para que los datos se puedan descargar desde Amazon S3 mediante flujos reales, 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 la opción de contexto del flujo de seekable.

Cargar datos

Puede cargar datos a Amazon S3 mediante file_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 encapsulador de flujo de Amazon S3 no permite leer y escribir flujos de forma 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);

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 flujos de Amazon S3 admite los siguientes modos para los flujos que se dirigen a objetos de Amazon S3.

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.

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

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

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

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

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

Trabajar con buckets y carpetas

Utilizar mkdir() para trabajar con buckets

Puede crear y explorar buckets de Amazon S3 de forma similar a cómo PHP le permite crear y recorrer directorios en su sistema de archivos.

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

mkdir('s3://my-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://my-bucket', 0500, true,
        stream_context_create([
            's3' => ['LocationConstraint' => 'eu-west-1']
        ]));

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

// Delete a bucket
rmdir('s3://my-bucket);

Utilizar mkdir() para trabajar con carpetas

Después de crear un bucket, puede utilizar mkdir() para crear objetos que funcionen como carpetas, tal y como ocurre en un sistema de archivos.

El siguiente fragmento de código añade un objeto de carpeta denominado «my-folder» al bucket existente denominado «my-bucket». Utilice la barra inclinada (/) para separar el nombre de un objeto de carpeta del nombre del depósito y de cualquier nombre de carpeta adicional.

mkdir('s3://my-bucket/my-folder')

La nota anterior sobre los cambios de permisos después de abril de 2023 también se aplica al crear objetos de carpeta. Esta entrada de blog contiene información sobre cómo ajustar los permisos si es necesario.

Utilice la función rmdir() para eliminar un objeto de carpeta vacío tal y como se muestra en el siguiente fragmento.

rmdir('s3://my-bucket/my-folder')

Mostrar el contenido de un bucket

Puede utilizar las funciones de PHP opendir(), readdir(), rewinddir() y closedir() en el encapsulador de flujo de Amazon S3 para revisar 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.