Wrapper de stream do Amazon S3 com o AWS SDK for PHP versão 3

O stream wrapper do Amazon S3 permite armazenar e recuperar dados do Amazon S3; usando funções embutidas do PHP, como file_get_contents, fopen, copy, rename, unlink, mkdir e rmdir.

Você precisa registrar o stream wrapper do Amazon S3 para usá-lo.

$client = new Aws\S3\S3Client([/** options **/]);

// Register the stream wrapper from an S3Client object
$client->registerStreamWrapper();

Deste modo, é possível acessar buckets e objetos armazenados no Amazon S3 por meio do protocolo s3://. O stream wrapper do Amazon S3 aceita sequências que contêm um nome do bucket seguido por uma barra e uma chave de objeto ou prefixo opcional: s3://<bucket>[/<key-or-prefix>].

Download de dados

Você pode capturar o conteúdo de um objeto usando file_get_contents. No entanto, tenha cuidado com essa função; ela carrega todo o conteúdo do objeto na memória.

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

Use fopen() ao trabalhar com arquivos maiores ou se precisar fazer fluxos de dados do 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);
}

Abra fluxos pesquisáveis

Os streams abertos no modo "r" só permitem que os dados sejam lidos no stream e não são pesquisáveis por padrão. Isso é para que o download dos dados possa ser feito no Amazon S3 na forma de streaming verdadeiro, onde os bytes lidos anteriormente não precisam ser armazenados em buffer na memória. Se você precisar que um stream seja pesquisável, você pode passar seekable para as opções do contexto de stream de uma função.

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

A abertura de streams pesquisáveis permite que você busque bytes que tenham sido lidos anteriormente. Você não pode pular para bytes que ainda não tenham sido lidos no servidor remoto. Para permitir que os dados lidos anteriormente sejam lembrados, os dados são armazenados em buffer em um stream temporário do PHP usando um decorador de stream. Quando a quantidade de dados em cache excede 2 MB, os dados no stream temporário são transferidos da memória para o disco. Lembre-se disso ao fazer download de arquivos grandes do Amazon S3 usando a configuração de contexto de stream seekable.

Carregar dados

Você pode fazer upload dos dados para o Amazon S3 usando file_put_contents().

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

Você pode fazer upload de arquivos maiores por dados de streaming usando fopen() e um modo de acesso de stream "w", "x" ou "a". O stream wrapper do Amazon S3 não é compatível com streams de leitura e gravação simultâneas (por exemplo, "r+", "w+", etc.). Isso ocorre porque o protocolo HTTP não permite leitura e gravação simultâneas.

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

Modos fopen

A função fopen() do PHP exige que você especifique uma opção $mode. O opção do modo especifica se os dados podem ser lidos ou gravados em um stream, e se o arquivo deve existir ao abrir um stream.

O wrapper de stream do Amazon S3 suporta os seguintes modos para streams que têm como alvo objetos do Amazon S3.

Outras funções de objetos

Os wrappers de stream permitem muitas funções diferentes do PHP embutidas para trabalhar com um sistema personalizado, como o Amazon S3. Estas são algumas das funções que o stream wrapper do Amazon S3 permite que você execute com objetos armazenados no 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!';
}

Trabalhe com buckets e pastas

Use mkdir() para trabalhar com buckets

Você pode criar e navegar pelos buckets do Amazon S3 da mesma forma que o PHP permite criar e percorrer diretórios no seu sistema de arquivos.

Aqui está um exemplo que cria um bucket.

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

É possível transmitir as opções de contexto de stream para o método mkdir() a fim de modificar a maneira como o bucket é criado usando os parâmetros disponíveis para a operação CreateBucket.

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

Você pode excluir buckets usando a função rmdir().

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

Use mkdir() para trabalhar com pastas

Depois de criar um bucket, você pode usar mkdir() para criar objetos que funcionam como pastas como em um sistema de arquivos.

O trecho de código a seguir adiciona um objeto de pasta chamado 'my-folder' ao bucket existente chamado 'my-bucket'. Use o caractere de barra (/) para separar um nome de objeto de pasta do nome do bucket e de qualquer nome de pasta adicional.

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

A observação anterior sobre alterações de permissão após abril de 2023 também entra em ação quando você cria objetos de pasta. Esta postagem do blog tem informações sobre como ajustar as permissões, se necessário.

Use a função rmdir() para excluir um objeto de pasta vazio, como mostrado no snippet a seguir.

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

Listar o conteúdo de qualquer bucket

Você pode usar as funções opendir(), readdir(), rewinddir() e closedir() do PHP com o stream wrapper do Amazon S3 para percorrer o conteúdo de um bucket. Você pode passar os parâmetros disponíveis para a operação ListObjects como opções de contexto de stream personalizado para a função opendir() para modificar a maneira como os objetos são listados.

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

Você pode listar cada objeto e prefixo recursivamente em um bucket usando RecursiveDirectoryIterator do PHP.

$dir = 's3://bucket';
$iterator = new RecursiveIteratorIterator(new RecursiveDirectoryIterator($dir));

foreach ($iterator as $file) {
    echo $file->getType() . ': ' . $file . "\n";
}

Outra forma de listar o conteúdo de um bucket recursivamente que incorre em um número menor de solicitações HTTP é usando a função 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";
}

Opções de contexto de stream

Você pode personalizar o cliente usado pelo stream wrapper ou o cache usado para armazenar em cache as informações carregadas anteriormente sobre buckets e chaves, passando as opções de contexto de stream personalizado.

O stream wrapper é compatível com as seguintes opções de contexto de stream em cada operação.