Armazenamento de Arquivos com Laravel S3

Tempo de leitura: 4 minutos

Armazenamento de Arquivos com Laravel S3: O Laravel Filesystem oferece uma API unificada e fluida para interagir com diversos sistemas de arquivos (ou Drivers), graças ao componente Flysystem do PHP. Essa abstração permite que você utilize o mesmo código para armazenar arquivos em um servidor local, em ambientes de teste, ou em serviços de cloud como o Amazon S3 (Simple Storage Service).

O uso do Laravel S3 é fundamental para aplicações escaláveis, que exigem durabilidade, alta disponibilidade e distribuição de conteúdo.

1. ⚙️ Configuração dos Discos de Armazenamento

A configuração de todos os destinos de armazenamento é centralizada no arquivo config/filesystems.php. Cada destino é chamado de Disco (Disk).

A. Drivers Comuns

Disco	Driver	Uso
`local`	`local`	Armazena arquivos diretamente no sistema de arquivos do servidor.
`public`	`local`	Semelhante ao `local`, mas destinado a arquivos acessíveis publicamente (requer symlink).
`s3`	`s3`	Usa o Amazon S3 ou serviços compatíveis (como DigitalOcean Spaces).

B. Configuração do Disco S3

Para usar o S3, você deve garantir que o pacote AWS SDK for PHP esteja instalado (composer require league/flysystem-aws-s3-v3) e configurar as credenciais no arquivo config/filesystems.php usando variáveis de ambiente.

PHP

// config/filesystems.php

'disks' => [
    // ...
    's3' => [
        'driver' => 's3',
        'key' => env('AWS_ACCESS_KEY_ID'),
        'secret' => env('AWS_SECRET_ACCESS_KEY'),
        'region' => env('AWS_DEFAULT_REGION'),
        'bucket' => env('AWS_BUCKET'), // O nome do seu bucket S3
        'url' => env('AWS_URL'), // Opcional, para CDN/CloudFront
    ],
],

2. 🗄️ Interagindo com Discos

Você interage com o sistema de arquivos usando a Facade Storage, especificando qual disco deseja usar através do método disk().

A. Obtendo uma Instância de Disco

PHP

use Illuminate\Support\Facades\Storage;

// Acessa o disco padrão (geralmente 'local')
$diskPadrao = Storage::drive(); 

// Acessa o disco S3
$s3Disk = Storage::disk('s3'); 

// Acessa o disco local público
$publicDisk = Storage::disk('public');

B. Armazenando Arquivos (Uploads)

O método mais comum para lidar com arquivos enviados via formulário é o store(), disponível no objeto UploadedFile. Ele lida com o streaming e retorna o caminho gerado.

PHP

// Exemplo: Armazenando um arquivo enviado por formulário no S3
// $request->file('arquivo') é uma instância de UploadedFile

// 'uploads' é o subdiretório dentro do bucket (ou disco)
// 's3' é o nome do disco
$path = $request->file('arquivo')->store('uploads', 's3');
// $path pode ser, por exemplo: uploads/u4dFj8lZk.jpg

Você também pode usar o método put() para armazenar conteúdo bruto (string, stream) diretamente:

PHP

// Armazenando conteúdo de texto em um arquivo no S3
Storage::disk('s3')->put('logs/erro-2025.txt', 'Conteúdo do log de erro');

C. Recuperando Conteúdo

Use o método get() para obter o conteúdo bruto do arquivo.

PHP

// Obtendo o conteúdo (string) de um arquivo no S3
$contents = Storage::disk('s3')->get('uploads/u4dFj8lZk.jpg');
x

3. 🌐 URLs e Visibilidade

A. Gerando URLs Públicas

Para o S3, os arquivos são privados por padrão. Você precisa usar o método url() ou temporaryUrl() para gerar um link acessível.

url(): Retorna a URL pública permanente. (A permissão do Bucket ou a visibility do arquivo deve permitir o acesso público).
PHP
$url = Storage::disk('s3')->url($path);
temporaryUrl(): Gera uma URL pré-assinada de curta duração para acesso privado e temporário (ideal para acesso restrito).
PHP
// URL válida por 5 minutos
$urlExpiravel = Storage::disk('s3')->temporaryUrl( $path, now()->addMinutes(5) );

B. Manipulando Visibilidade

Você pode definir se um arquivo é public (acessível via URL) ou private (requer autenticação ou URL temporária).

PHP

// Torna o arquivo publicamente acessível
Storage::disk('s3')->setVisibility($path, 'public');

// Torna o arquivo privado
Storage::disk('s3')->setVisibility($path, 'private');

4. 🗑️ Excluindo e Verificando

Método	Função	Exemplo
`delete()`	Remove um ou mais arquivos.	`Storage::disk('s3')->delete($path);`
`exists()`	Verifica se um arquivo existe no disco.	`if (Storage::disk('s3')->exists($path)) { /* ... */ }`
`size()`	Retorna o tamanho do arquivo em bytes.	`$tamanho = Storage::disk('s3')->size($path);`

✅ Conclusão Armazenamento de Arquivos com Laravel S3

Armazenamento de Arquivos com Laravel S3: O sistema Laravel Filesystem (Flysystem) fornece uma API unificada que facilita o gerenciamento de arquivos. A configuração do disco S3 no config/filesystems.php é a ponte para o armazenamento em nuvem escalável. Ao usar métodos como store() para uploads e url() ou temporaryUrl() para acesso, você garante que sua aplicação lide com grandes volumes de arquivos de forma eficiente e durável.

Mas antes de dominar o Laravel, se for o seu caso, toda jornada tem um início. Vamos entender quais são os conhecimentos básicos necessários para aproveitar ao máximo este poderoso framework. Para iniciar seus estudos no Laravel, você precisará dominar as seguintes tecnologias: