Flysystem para PHP: guía completa con ejemplos

¿Qué es Flysystem y para qué sirve?

\n\n

Flysystem es una potente biblioteca para PHP que proporciona una interfaz única y unificada para trabajar con diferentes sistemas de archivos. Desarrollada por Frank de Jonge, resuelve un problema fundamental: en proyectos reales, el código a menudo está fuertemente acoplado a un sistema de archivos específico (disco local, FTP, Amazon S3, Dropbox, etc.). Si mañana necesitas migrar el almacenamiento de archivos de un servidor local a la nube, tendrías que reescribir una parte significativa del código.

\n\n

Flysystem abstrae esta complejidad. Escribes el código una vez, usando una API unificada, y puedes cambiar el "adaptador" (controlador) del sistema de archivos sin modificar la lógica de negocio de la aplicación. Esto hace que tu código sea:

\n

\n
• Flexible — fácil de cambiar entre almacenamientos.
\n
• Comprobable — puedes usar un sistema de archivos "falso" en las pruebas.
\n
• Portátil — el código funciona igual en diferentes entornos.
\n

\n\n

La biblioteca se utiliza en proyectos conocidos como Laravel (como base para el disco de almacenamiento), Symfony, Drupal y muchos otros. Flysystem admite decenas de adaptadores: Local, FTP/SFTP, Amazon S3, Google Cloud Storage, Azure Blob Storage, WebDAV, Dropbox e incluso archivos cifrados y Zip.

\n\n

Instalación

\n\n

Flysystem se instala a través de Composer. Para el trabajo básico con el sistema de archivos local, son suficientes dos paquetes:

\n\n

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

\n\n

Importante: A partir de la versión 3.x, Flysystem utiliza una arquitectura separada. El paquete principal league/flysystem contiene solo las interfaces y clases base. Los adaptadores (controladores) se instalan por separado. Esto permite conectar solo lo que realmente se necesita.

\n\n

Para otros sistemas de archivos:

\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 pruebas (sistema de archivos virtual en memoria)
\n

\n\n

Inicio rápido

\n\n

Creemos un ejemplo simple: escritura, lectura y eliminación de un archivo en el disco local.

\n\n

<?php\nrequire 'vendor/autoload.php';\n\nuse League\\Flysystem\\Filesystem;\nuse League\\Flysystem\\Local\\LocalFilesystemAdapter;\n\n// 1. Creamos el adaptador para el sistema de archivos local\n// Especificamos el directorio raíz donde se almacenarán los archivos\n$adapter = new LocalFilesystemAdapter(__DIR__ . '/storage');\n\n// 2. Creamos una instancia de Filesystem\n$filesystem = new Filesystem($adapter);\n\n// 3. Escribimos un archivo\n$filesystem->write('hello.txt', '¡Hola, mundo!');\n\n// 4. Leemos el archivo\n$content = $filesystem->read('hello.txt');\necho $content; // Mostrará: ¡Hola, mundo!\n\n// 5. Verificamos si el archivo existe\nif ($filesystem->fileExists('hello.txt')) {\n    echo "¡El archivo existe!";\n}\n\n// 6. Eliminamos el archivo\n$filesystem->delete('hello.txt');\n\n// 7. Verificamos que el archivo ya no existe\necho $filesystem->fileExists('hello.txt') ? 'Sí' : 'No'; // Mostrará: No\n?>

\n\n

Observa: no usamos file_put_contents(), fopen() ni otras funciones nativas de PHP. Todo el código funciona a través de la interfaz unificada Filesystem.

\n\n

Métodos/funciones principales

\n\n

Veamos los métodos clave de Flysystem. Todos los ejemplos asumen que ya tienes un objeto $filesystem creado.

\n\n

1. write() — Escribir un nuevo archivo

\n

Qué hace: Crea un nuevo archivo o sobrescribe uno existente.

\n

Parámetros:

\n

\n
• string $path — ruta al archivo
\n
• string|resource $contents — contenido del archivo (cadena o recurso)