Trabalhando com S3 e armazenamentos em nuvem em PHP: guia completo

Trabalhando com S3 e armazenamentos em nuvem em PHP

Os armazenamentos de objetos em nuvem compatíveis com o protocolo Amazon S3 (Simple Storage Service) tornaram-se o padrão de facto para armazenar arquivos, imagens, backups e conteúdo estático. O PHP fornece ferramentas poderosas para integração com esses armazenamentos, como AWS S3, MinIO (self-hosted), DigitalOcean Spaces, Wasabi, Yandex Object Storage e outros. Neste artigo, veremos detalhadamente como trabalhar com armazenamentos compatíveis com S3 em PHP, usando o AWS SDK oficial e bibliotecas alternativas.

Conceitos básicos do S3

Antes de ir para o código, é importante entender os conceitos-chave do S3:

• Bucket — contêiner para objetos (arquivos). O nome do bucket deve ser globalmente único (para nuvens públicas).
• Objeto (Object) — arquivo e seus metadados. Cada objeto tem uma chave (Key) — o caminho para o arquivo dentro do bucket.
• Região (Region) — localização geográfica do armazenamento.
• Credentials — chave de acesso (Access Key ID) e chave secreta (Secret Access Key) para autenticação.
• Endpoint — URL do armazenamento (para serviços compatíveis com S3 diferentes da AWS, o endpoint é obrigatório).

Instalação do AWS SDK para PHP

A biblioteca oficial para trabalhar com S3 é aws/aws-sdk-php. Instalação via Composer:

composer require aws/aws-sdk-php

Para trabalhar com MinIO ou DigitalOcean Spaces, não são necessárias dependências adicionais — o SDK suporta endpoints personalizados.

Configuração básica do cliente S3

Vamos criar um cliente para conectar ao AWS S3:

<?phprequire 'vendor/autoload.php';

use Aws\\S3\\S3Client;use Aws\\Exception\\AwsException;

$s3Client = new S3Client([    'version'     => 'latest',    'region'      => 'us-east-1',    'credentials' => [        'key'    => 'YOUR_ACCESS_KEY',        'secret' => 'YOUR_SECRET_KEY',    ],]);?>

Para MinIO (armazenamento local compatível com S3), a configuração será assim:

<?php$s3Client = new S3Client([    'version'     => 'latest',    'region'      => 'us-east-1', // MinIO ignora a região    'endpoint'    => 'http://localhost:9000',    'use_path_style_endpoint' => true,    'credentials' => [        'key'    => 'minioadmin',        'secret' => 'minioadmin',    ],]);?>

Observe o parâmetro use_path_style_endpoint — ele é necessário para MinIO e alguns armazenamentos não-AWS.

Gerenciamento de buckets

Criação de bucket

<?phptry {    $result = $s3Client->createBucket([        'Bucket' => 'my-php-bucket',    ]);    echo "Bucket criado: " . $result['Location'];} catch (AwsException $e) {    echo "Erro: " . $e->getMessage();}?>

Verificação de existência do bucket

<?php$exists = $s3Client->doesBucketExist('my-php-bucket');if ($exists) {    echo "O bucket existe";} else {    echo "Bucket não encontrado";}?>

Lista de todos os buckets

<?php$buckets = $s3Client->listBuckets();foreach ($buckets['Buckets'] as $bucket) {    echo $bucket['Name'] . " (criado em: " . $bucket['CreationDate'] . ")<br>";}?>

Upload de arquivos para S3

Upload a partir de string (dados de texto)

<?phptry {    $result = $s3Client->putObject([        'Bucket' => 'my-php-bucket',        'Key'    => 'hello.txt',        'Body'   => 'Olá, S3 do PHP!',    ]);    echo "Arquivo enviado. URL: " . $result['ObjectURL'];} catch (AwsException $e) {    echo "Erro no upload: "