Flysystem
Provides filesystem abstraction layer for Drupal using the PHP League's Flysystem library, allowing easy swapping between local and remote filesystems.
flysystem
Install
composer require 'drupal/flysystem:^2.3'
composer require 'drupal/flysystem:^2.2'
Overview
Flysystem for Drupal integrates the powerful PHP League's Flysystem library with Drupal's stream wrapper system. This enables site administrators and developers to seamlessly use various filesystem backends (local, FTP, cloud storage, etc.) through a unified API, reducing technical debt and eliminating vendor lock-in.
The module registers custom stream wrappers based on configuration in settings.php, making files accessible through URIs like 'scheme-name://path/to/file.txt'. It supports features like file replication across multiple backends, metadata caching using Drupal's Cache API, and serving CSS/JS assets from remote filesystems (useful for CDN integration).
The plugin architecture allows additional adapters to be installed via contrib modules, including Dropbox, Rackspace, Amazon S3, SFTP, and ZIP archive support. Image styles work seamlessly with remote filesystems, automatically generating derivative images on demand.
Features
- Integrates PHP League's Flysystem library with Drupal's stream wrapper system for unified filesystem access
- Built-in support for local filesystem and FTP adapters with extensible plugin architecture
- File replication feature writes to multiple filesystems simultaneously for backup purposes
- Metadata caching using Drupal's Cache API to reduce remote filesystem calls
- CSS and JS asset serving from custom stream wrappers for CDN integration
- Full image style support with on-demand derivative generation for remote filesystems
- Administrator UI for synchronizing files between different filesystem backends
- Automatic .htaccess file creation for security protection on local filesystems
- System status page integration showing filesystem health and configuration errors
- Hook implementations (cron, rebuild) to ensure filesystem integrity automatically
Use Cases
Migrating files to cloud storage
Use Flysystem to gradually migrate files from local storage to Amazon S3 or other cloud providers. Configure both local and S3 schemes, use the replication feature to write to both during transition, then switch to S3-only once migration is complete.
CDN integration for assets
Configure a scheme with serve_js and serve_css options enabled to serve aggregated CSS and JavaScript files from a CDN-backed storage like S3 with CloudFront. This offloads static asset delivery from your web servers.
Secure file storage
Store sensitive files on a separate filesystem (FTP server, private S3 bucket) that is not directly web-accessible. Files are served through Drupal's access control system.
Distributed file system
In a multi-server environment, use a shared remote filesystem (S3, network storage) to ensure all application servers have access to the same files without synchronization issues.
File backup and redundancy
Use the replicate configuration option to automatically write all files to a backup filesystem. Primary reads come from the fast local storage while writes go to both local and remote backup.
Development/staging file sharing
Use a common remote storage backend across development, staging, and production environments to share user-uploaded files without manual synchronization.
Tips
- Stream wrapper scheme names cannot contain underscores - use hyphens instead (e.g., 'my-files' not 'my_files')
- Enable the cache option for remote filesystems to reduce API calls and improve performance
- Use the replicate feature during migrations to maintain file availability while transitioning storage backends
- Check /admin/reports/status regularly - Flysystem runs validation on every page load in development and reports issues
- For local public filesystems, ensure the root path is relative to the Drupal installation root for direct URL access to work
- The module automatically creates directories and .htaccess files on install and cron runs
Technical Details
Admin Pages 1
/admin/config/media/file-system/flysystem
Synchronize files between different Flysystem filesystem backends. This page allows administrators to copy all files from one configured stream wrapper to another, useful for migrating files between storage backends or creating backups.
Permissions 1
Hooks 5
hook_cron
Calls flysystem_factory->ensure() on every cron run to validate filesystem configurations and log any errors.
hook_rebuild
Calls flysystem_factory->ensure() when the Drupal cache is rebuilt to ensure filesystem directories exist and are properly configured.
hook_file_download
Handles file downloads for Flysystem-managed files, returning appropriate Content-Type and Content-Length headers.
hook_requirements
Validates Flysystem configuration during install and runtime, checking for invalid scheme names, missing dependencies, and filesystem errors.
hook_install
Calls flysystem_factory->ensure() when the module is installed to create necessary directories and .htaccess files.
Troubleshooting 6
Check /admin/reports/status for Flysystem-specific error messages. Verify the scheme name follows the required format (letters, numbers, +, ., - only, no underscores). Ensure the directory path exists and is writable.
Ensure the web server has write permissions to the root directory. The module will report this error on the status page with a link to Drupal security advisory SA-CORE-2013-003.
Verify the PHP FTP extension is installed (check phpinfo()). Confirm host, port, username, and password are correct. Try enabling passive mode if behind a firewall.
Ensure the image module is enabled. Check that the file exists on the source filesystem. Image style generation uses locking to prevent race conditions - check for lock issues.
Run composer require drupal/flysystem to ensure all dependencies (league/flysystem, league/flysystem-replicate-adapter, twistor/flysystem-stream-wrapper) are installed.
Clear all Drupal caches with drush cr. Stream wrappers are registered during container compilation, so changes to settings.php require a cache rebuild.
Security Notes 5
- The 'administer flysystem' permission is marked as restricted due to the sensitive nature of filesystem operations
- Local filesystem adapters automatically create .htaccess files to prevent direct execution of uploaded PHP files
- FTP credentials are stored in plain text in settings.php - ensure proper file permissions on this file
- When using public local filesystems, ensure the root directory is within the web root for proper URL generation
- The replication feature writes to both filesystems - ensure both destinations have appropriate access controls