Flysystem
Provides filesystem abstraction layer for Drupal using the PHP League's Flysystem library, allowing easy swapping between local and remote filesystems.
flysystem
インストール
composer require 'drupal/flysystem:^2.3'
composer require 'drupal/flysystem:^2.2'
概要
Flysystem for Drupalは、強力なPHP LeagueのFlysystemライブラリをDrupalのストリームラッパーシステムと統合します。これにより、サイト管理者や開発者は、統一されたAPIを通じてさまざまなファイルシステムバックエンド（ローカル、FTP、クラウドストレージなど）をシームレスに使用でき、技術的負債を削減し、ベンダーロックインを排除できます。
このモジュールはsettings.phpの設定に基づいてカスタムストリームラッパーを登録し、'scheme-name://path/to/file.txt'のようなURIでファイルにアクセスできるようにします。複数のバックエンドにわたるファイルレプリケーション、DrupalのCache APIを使用したメタデータキャッシュ、リモートファイルシステムからのCSS/JSアセット配信（CDN統合に便利）などの機能をサポートしています。
プラグインアーキテクチャにより、Dropbox、Rackspace、Amazon S3、SFTP、ZIPアーカイブサポートなど、追加のアダプターをcontribモジュール経由でインストールできます。イメージスタイルはリモートファイルシステムとシームレスに動作し、必要に応じて派生画像を自動生成します。
Features
- PHP LeagueのFlysystemライブラリをDrupalのストリームラッパーシステムと統合し、統一されたファイルシステムアクセスを提供
- 拡張可能なプラグインアーキテクチャを備えたローカルファイルシステムおよびFTPアダプターの組み込みサポート
- バックアップ目的で複数のファイルシステムに同時に書き込むファイルレプリケーション機能
- DrupalのCache APIを使用したメタデータキャッシュにより、リモートファイルシステムへの呼び出しを削減
- CDN統合のためのカスタムストリームラッパーからのCSSおよびJSアセット配信
- リモートファイルシステム用のオンデマンド派生画像生成を伴う完全なイメージスタイルサポート
- 異なるファイルシステムバックエンド間でファイルを同期するための管理者UI
- ローカルファイルシステムでのセキュリティ保護のための.htaccessファイル自動作成
- ファイルシステムの健全性と設定エラーを表示するシステムステータスページ統合
- ファイルシステムの整合性を自動的に確保するフック実装（cron、rebuild）
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.
権限 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