Flysystem
Proporciona una capa de abstracción de sistema de archivos para Drupal utilizando la biblioteca Flysystem de PHP League, permitiendo el intercambio fácil entre sistemas de archivos locales y remotos.
flysystem
Install
composer require 'drupal/flysystem:^2.3'
composer require 'drupal/flysystem:^2.2'
Overview
Flysystem para Drupal integra la potente biblioteca Flysystem de PHP League con el sistema de stream wrappers de Drupal. Esto permite a los administradores del sitio y desarrolladores utilizar de forma transparente varios backends de sistema de archivos (local, FTP, almacenamiento en la nube, etc.) a través de una API unificada, reduciendo la deuda técnica y eliminando la dependencia de proveedores.
El módulo registra stream wrappers personalizados basados en la configuración en settings.php, haciendo que los archivos sean accesibles a través de URIs como 'nombre-esquema://ruta/al/archivo.txt'. Soporta características como la replicación de archivos en múltiples backends, almacenamiento en caché de metadatos usando la Cache API de Drupal, y servir recursos CSS/JS desde sistemas de archivos remotos (útil para integración con CDN).
La arquitectura de plugins permite instalar adaptadores adicionales mediante módulos contrib, incluyendo soporte para Dropbox, Rackspace, Amazon S3, SFTP y archivos ZIP. Los estilos de imagen funcionan perfectamente con sistemas de archivos remotos, generando automáticamente imágenes derivadas bajo demanda.
Features
- Integra la biblioteca Flysystem de PHP League con el sistema de stream wrappers de Drupal para acceso unificado al sistema de archivos
- Soporte integrado para adaptadores de sistema de archivos local y FTP con arquitectura de plugins extensible
- Función de replicación de archivos que escribe en múltiples sistemas de archivos simultáneamente para propósitos de respaldo
- Almacenamiento en caché de metadatos usando la Cache API de Drupal para reducir las llamadas al sistema de archivos remoto
- Servicio de recursos CSS y JS desde stream wrappers personalizados para integración con CDN
- Soporte completo de estilos de imagen con generación de derivados bajo demanda para sistemas de archivos remotos
- Interfaz de administración para sincronizar archivos entre diferentes backends de sistema de archivos
- Creación automática de archivo .htaccess para protección de seguridad en sistemas de archivos locales
- Integración con la página de estado del sistema mostrando la salud del sistema de archivos y errores de configuración
- Implementaciones de hooks (cron, rebuild) para asegurar la integridad del sistema de archivos automáticamente
Use Cases
Migración de archivos a almacenamiento en la nube
Use Flysystem para migrar gradualmente archivos del almacenamiento local a Amazon S3 u otros proveedores de nube. Configure tanto el esquema local como el de S3, use la función de replicación para escribir en ambos durante la transición, luego cambie a solo S3 una vez que la migración esté completa.
Integración de CDN para recursos
Configure un esquema con las opciones serve_js y serve_css habilitadas para servir archivos CSS y JavaScript agregados desde un almacenamiento respaldado por CDN como S3 con CloudFront. Esto descarga la entrega de recursos estáticos de sus servidores web.
Almacenamiento seguro de archivos
Almacene archivos sensibles en un sistema de archivos separado (servidor FTP, bucket privado de S3) que no sea directamente accesible vía web. Los archivos se sirven a través del sistema de control de acceso de Drupal.
Sistema de archivos distribuido
En un entorno multi-servidor, use un sistema de archivos remoto compartido (S3, almacenamiento en red) para asegurar que todos los servidores de aplicación tengan acceso a los mismos archivos sin problemas de sincronización.
Respaldo y redundancia de archivos
Use la opción de configuración replicate para escribir automáticamente todos los archivos en un sistema de archivos de respaldo. Las lecturas primarias vienen del almacenamiento local rápido mientras que las escrituras van tanto al local como al respaldo remoto.
Compartir archivos entre desarrollo/staging
Use un backend de almacenamiento remoto común en los entornos de desarrollo, staging y producción para compartir archivos subidos por usuarios sin sincronización manual.
Tips
- Los nombres de esquema de stream wrapper no pueden contener guiones bajos - use guiones en su lugar (por ejemplo, 'my-files' no 'my_files')
- Habilite la opción cache para sistemas de archivos remotos para reducir llamadas a la API y mejorar el rendimiento
- Use la función de replicación durante migraciones para mantener la disponibilidad de archivos mientras transiciona backends de almacenamiento
- Revise /admin/reports/status regularmente - Flysystem ejecuta validación en cada carga de página en desarrollo y reporta problemas
- Para sistemas de archivos públicos locales, asegúrese de que la ruta raíz sea relativa a la raíz de instalación de Drupal para que el acceso por URL directa funcione
- El módulo crea automáticamente directorios y archivos .htaccess durante la instalación y ejecución de cron
Technical Details
Admin Pages 1
/admin/config/media/file-system/flysystem
Sincroniza archivos entre diferentes backends de sistema de archivos Flysystem. Esta página permite a los administradores copiar todos los archivos de un stream wrapper configurado a otro, útil para migrar archivos entre backends de almacenamiento o crear respaldos.
Permissions 1
Hooks 5
hook_cron
Llama a flysystem_factory->ensure() en cada ejecución de cron para validar las configuraciones del sistema de archivos y registrar cualquier error.
hook_rebuild
Llama a flysystem_factory->ensure() cuando se reconstruye la caché de Drupal para asegurar que los directorios del sistema de archivos existan y estén correctamente configurados.
hook_file_download
Maneja las descargas de archivos gestionados por Flysystem, devolviendo los encabezados Content-Type y Content-Length apropiados.
hook_requirements
Valida la configuración de Flysystem durante la instalación y en tiempo de ejecución, verificando nombres de esquemas inválidos, dependencias faltantes y errores del sistema de archivos.
hook_install
Llama a flysystem_factory->ensure() cuando se instala el módulo para crear los directorios necesarios y archivos .htaccess.
Troubleshooting 6
Revise /admin/reports/status para mensajes de error específicos de Flysystem. Verifique que el nombre del esquema siga el formato requerido (solo letras, números, +, ., - sin guiones bajos). Asegúrese de que la ruta del directorio exista y tenga permisos de escritura.
Asegúrese de que el servidor web tenga permisos de escritura en el directorio raíz. El módulo reportará este error en la página de estado con un enlace al aviso de seguridad de Drupal SA-CORE-2013-003.
Verifique que la extensión PHP FTP esté instalada (revise phpinfo()). Confirme que el host, puerto, nombre de usuario y contraseña sean correctos. Intente habilitar el modo pasivo si está detrás de un firewall.
Asegúrese de que el módulo image esté habilitado. Verifique que el archivo exista en el sistema de archivos de origen. La generación de estilos de imagen usa bloqueo para prevenir condiciones de carrera - revise si hay problemas de bloqueo.
Ejecute composer require drupal/flysystem para asegurar que todas las dependencias (league/flysystem, league/flysystem-replicate-adapter, twistor/flysystem-stream-wrapper) estén instaladas.
Limpie todas las cachés de Drupal con drush cr. Los stream wrappers se registran durante la compilación del contenedor, por lo que los cambios en settings.php requieren una reconstrucción de caché.
Security Notes 5
- El permiso 'administer flysystem' está marcado como restringido debido a la naturaleza sensible de las operaciones del sistema de archivos
- Los adaptadores de sistema de archivos local crean automáticamente archivos .htaccess para prevenir la ejecución directa de archivos PHP subidos
- Las credenciales FTP se almacenan en texto plano en settings.php - asegúrese de tener permisos de archivo apropiados en este archivo
- Cuando use sistemas de archivos locales públicos, asegúrese de que el directorio raíz esté dentro del directorio web raíz para la generación correcta de URLs
- La función de replicación escribe en ambos sistemas de archivos - asegúrese de que ambos destinos tengan controles de acceso apropiados