Flysystem para PHP: guia completo com exemplos

O que é Flysystem e para que serve?

\n\n

Flysystem é uma biblioteca poderosa para PHP que fornece uma interface única e unificada para trabalhar com diferentes sistemas de arquivos. Desenvolvida por Frank de Jonge, ela resolve um problema fundamental: em projetos reais, o código frequentemente fica rigidamente vinculado a um sistema de arquivos específico (disco local, FTP, Amazon S3, Dropbox, etc.). Se amanhã for necessário migrar o armazenamento de arquivos do servidor local para a nuvem, grande parte do código precisará ser reescrita.

\n\n

Flysystem abstrai essa complexidade. Você escreve o código uma vez, usando uma API unificada, e pode trocar o "adaptador" (driver) do sistema de arquivos sem alterar a lógica de negócios da aplicação. Isso torna seu código:

\n

\n
• Flexível — fácil alternar entre armazenamentos.
\n
• Testável — é possível usar um sistema de arquivos "falso" em testes.
\n
• Portável — o código funciona da mesma forma em diferentes ambientes.
\n

\n\n

A biblioteca é usada em projetos conhecidos como Laravel (como base para o disco de armazenamento), Symfony, Drupal e muitos outros. Flysystem suporta dezenas de adaptadores: Local, FTP/SFTP, Amazon S3, Google Cloud Storage, Azure Blob Storage, WebDAV, Dropbox e até arquivos criptografados e Zip.

\n\n

Instalação

\n\n

Flysystem é instalado via Composer. Para o funcionamento básico com o sistema de arquivos local, dois pacotes são suficientes:

\n\n

composer require league/flysystem\ncomposer require league/flysystem-local

\n\n

Importante: A partir da versão 3.x, o Flysystem usa uma arquitetura separada. O pacote principal league/flysystem contém apenas interfaces e classes base. Os adaptadores (drivers) são instalados separadamente. Isso permite incluir apenas o que realmente é necessário.

\n\n

Para outros sistemas de arquivos:

\n

\n
• composer require league/flysystem-ftp — para FTP/SFTP
\n
• composer require league/flysystem-aws-s3-v3 — para Amazon S3
\n
• composer require league/flysystem-google-cloud-storage — para Google Cloud
\n
• composer require league/flysystem-memory — para testes (sistema de arquivos virtual in-memory)
\n

\n\n

Início rápido

\n\n

Vamos criar um exemplo simples: escrever, ler e excluir um arquivo no disco local.

\n\n

<?php\nrequire 'vendor/autoload.php';\n\nuse League\\Flysystem\\Filesystem;\nuse League\\Flysystem\\Local\\LocalFilesystemAdapter;\n\n// 1. Cria o adaptador para o sistema de arquivos local\n// Especifica o diretório raiz onde os arquivos serão armazenados\n$adapter = new LocalFilesystemAdapter(__DIR__ . '/storage');\n\n// 2. Cria a instância do Filesystem\n$filesystem = new Filesystem($adapter);\n\n// 3. Escreve o arquivo\n$filesystem->write('hello.txt', 'Olá, mundo!');\n\n// 4. Lê o arquivo\n$content = $filesystem->read('hello.txt');\necho $content; // Exibirá: Olá, mundo!\n\n// 5. Verifica se o arquivo existe\nif ($filesystem->fileExists('hello.txt')) {\n    echo "O arquivo existe!";\n}\n\n// 6. Exclui o arquivo\n$filesystem->delete('hello.txt');\n\n// 7. Verifica que o arquivo não existe mais\necho $filesystem->fileExists('hello.txt') ? 'Sim' : 'Não'; // Exibirá: Não\n?>

\n\n

Observe: não usamos file_put_contents(), fopen() ou outras funções nativas do PHP. Todo o código funciona através da interface unificada Filesystem.

\n\n

Principais métodos/funções

\n\n

Vamos analisar os métodos-chave do Flysystem. Todos os exemplos assumem que você já criou o objeto $filesystem.

\n\n

1. write() — Escrever um novo arquivo

\n

O que faz: Cria um novo arquivo ou sobrescreve um existente.

\n

Parâmetros:

\n

\n
• string $path — caminho para o arquivo
\n
• string|resource $contents — conteúdo do arquivo (string ou