]`.
**nota**
O stream wrapper é projetado para trabalhar com objetos e buckets nos quais você tenha pelo menos permissão de leitura. Isso significa que o usuário deve ter permissão para executar `ListBucket` em qualquer bucket, e `GetObject` em qualquer objeto com o qual o usuário precisa interagir. Para casos de uso em que você não tenha esse nível de permissão, recomendamos usar as operações de cliente do Amazon S3 diretamente.
## 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);
}
```
**nota**
Os erros de gravação de arquivos só são retornados quando uma chamada `fflush` é feita. Esses erros não são retornados quando um `fclose` não liberado é chamado. O valor de retorno de `fclose` será `true` se ele fechar o stream, independentemente de qualquer erro em resposta ao `fflush` interno. Esses erros também não são retornados ao chamar `file_put_contents` devido ao modo como o PHP o implementa.
### Abrir 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](http://www.php.net/manual/en/function.stream-context-create.php) 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 baixar arquivos grandes do Amazon S3 usando a configuração de contexto de fluxo `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 wrapper de fluxo do Amazon S3 **não** é compatível com fluxos 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);
```
**nota**
O Amazon S3 exige que um cabeçalho Content-Length seja especificado antes que a carga de uma solicitação seja enviada. Portanto, os dados a serem carregados em uma operação `PutObject` são armazenados em buffer internamente usando um stream temporário do PHP até que o stream seja liberado ou fechado.
**nota**
Os erros de gravação são retornados apenas quando é feita uma chamada para `fflush`. Esses erros não são retornados quando um `fclose` não liberado é chamado. O valor de retorno de `fclose` será `true` se ele fechar o stream, independentemente de qualquer erro em resposta ao `fflush` interno. Esses erros também não são retornados ao chamar `file_put_contents` devido ao modo como o PHP o implementa.
## Modos fopen
A função [fopen()](http://php.net/manual/en/function.fopen.php) 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 fluxo do Amazon S3 permite os seguintes modos para fluxos que têm como alvo objetos do Amazon S3.
****
| | |
| --- |--- |
| r | Um fluxo somente leitura onde o objeto já deve existir. |
| w | Um stream somente gravação. Se o objeto já existir, ele será substituído. |
| a | Um stream somente gravação. Se o objeto já existir, ele será baixado para um fluxo temporário e todas as gravações no fluxo serão acrescentadas a qualquer dado carregado anteriormente. |
| x | Um stream somente gravação. Será gerado um erro se o objeto já existir. |
## Outras funções de objetos
Os wrappers de fluxo 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.
****
| | |
| --- |--- |
| unlink() | Excluir um objeto de um bucket.// Delete an object from a bucket
unlink('s3://bucket/key');
Você pode passar todas as opções disponíveis para a operação `DeleteObject` para modificar a forma como o objeto é excluído (por exemplo, especificando a versão de um objeto específico).// Delete a specific version of an object from a bucket
unlink('s3://bucket/key', stream_context_create([
's3' => ['VersionId' => '123']
]);
|
| filesize() | Obter o tamanho de um objeto.// Get the Content-Length of an object
$size = filesize('s3://bucket/key', );
|
| is\_file() | Verifica se uma URL é um arquivo.if (is_file('s3://bucket/key')) {
echo 'It is a file!';
} |
| file\_exists() | Verifica se um objeto existe.if (file_exists('s3://bucket/key')) {
echo 'It exists!';
} |
| filetype() | Verifica se uma URL é mapeada para um arquivo ou bucket (dir). |
| file() | Carrega o conteúdo de um objeto em uma matriz de linhas. Você pode passar todas as opções disponíveis para a operação `GetObject` para modificar como o arquivo é obtido por download. |
| filemtime() | Obtém a data da última modificação de um objeto. |
| rename() | Renomeia um objeto copiando-o e excluindo o original. Você pode passar as opções disponíveis para as operações `CopyObject` e `DeleteObject` para os parâmetros do contexto do stream para modificar a maneira como o objeto é copiado e excluído. |
**nota**
Embora `copy` normalmente funcione com o wrapper de fluxo do Amazon S3, alguns erros podem não ser relatados corretamente devido às partes internas da função `copy` no PHP. Em vez disso, recomendamos que você use uma instância do [awSS3 ObjectCopier](https://docs.aws.amazon.com/aws-sdk-php/v3/api/class-Aws.S3.ObjectCopier.html).
## Trabalhar com buckets e pastas
### Usar `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://amzn-s3-demo-bucket');
```
**nota**
Em abril de 2023, o Amazon S3 habilitou automaticamente o Bloqueio de Acesso Público do S3 e desabilitou as listas de controle de acesso para todos os buckets recém-criados. Essa mudança também afeta a forma como `StreamWrapper` a `mkdir` função funciona com permissões ACLs e. Mais informações estão disponíveis neste [AWS artigo O que há de novo com](https://aws.amazon.com/about-aws/whats-new/2022/12/amazon-s3-automatically-enable-block-public-access-disable-access-control-lists-buckets-april-2023/).
Você pode passar as opções de contexto do stream para o `mkdir()` método para modificar a forma como o bucket é criado usando os parâmetros disponíveis para a [CreateBucket](https://docs.aws.amazon.com/aws-sdk-php/v3/api/class-Aws.S3.S3Client.html#_createBucket)operação.
```
// Create a bucket in the EU (Ireland) Region
mkdir('s3://amzn-s3-demo-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://amzn-s3-demo-bucket);
```
**nota**
Um bucket só pode ser excluído se estiver vazio.
### Usar `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 denominado “my-folder” ao bucket existente denominado “amzn-s3-demo-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://amzn-s3-demo-bucket/my-folder')
```
A [observação anterior](#work-with-buckets-create) sobre alterações de permissão após abril de 2023 também entra em ação quando você cria objetos de pasta. [Esta publicação do blog](https://aws.amazon.com/blogs/aws/heads-up-amazon-s3-security-changes-are-coming-in-april-of-2023/) 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 trecho a seguir.
```
rmdir('s3://amzn-s3-demo-bucket/my-folder')
```
### Listar o conteúdo de um bucket
Você pode usar as funções [opendir()](http://www.php.net/manual/en/function.opendir.php), [readdir()](http://www.php.net/manual/en/function.readdir.php), [rewinddir()](http://www.php.net/manual/en/function.rewinddir.php) e [closedir()](http://php.net/manual/en/function.closedir.php) do PHP com o wrapper de fluxo do Amazon S3 para percorrer o conteúdo de um bucket. Você pode passar os parâmetros disponíveis para a [ListObjects](https://docs.aws.amazon.com/aws-sdk-php/v3/api/class-Aws.S3.S3Client.html#_listObjects)operação como opções personalizadas de contexto de fluxo para a `opendir()` função para modificar a forma 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 recursivamente cada objeto e prefixo em um bucket usando o PHP. [RecursiveDirectoryIterator](http://php.net/manual/en/class.recursivedirectoryiterator.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)`.
```
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.
** `client` **
O objeto `Aws\AwsClientInterface` a ser usado para executar comandos.
** `cache` **
Uma instância de `Aws\CacheInterface` a ser usada para armazenar em cache as estatísticas de arquivos obtidas anteriormente. Por padrão, o stream wrapper usa um cache LRU na memória.