Flysystem Local Laravel Package

Getting Started

1. Install via Composer: composer require league/flysystem-local.
2. Instantiate the adapter with a local root path (e.g., storage_path('app') in Laravel):

   use League\Flysystem\Local\LocalFilesystemAdapter;
   $adapter = new LocalFilesystemAdapter('/path/to/root');
   

3. Wrap in Filesystem:

   use League\Flysystem\Filesystem;
   $filesystem = new Filesystem($adapter);
   

4. First operation: Write and read a file:

   $filesystem->write('test.txt', 'Hello');
   $content = $filesystem->read('test.txt');
   

Begin with the Local Adapter docs for full API details.

Implementation Patterns

• Laravel integration: Use League\Flysystem\Adapter\Local\LocalFilesystemAdapter in custom disk config (via config/filesystems.php) or build a Storage::extend() closure.
• Environment-driven paths: Define root via .env (e.g., FILESYSTEM_DISK_ROOT=storage/app) and inject into the adapter for different environments.
• Atomic writes: Use writeStream() for large files to avoid memory spikes; pair with temporary files and rename() for atomic uploads.
• Testing isolation: In unit tests, inject a sys_get_temp_dir()-backed adapter or use League\Flysystem\Memory\MemoryFilesystemAdapter for speed and safety.
• Batch management: Use listContents('', true) recursively for migrations, cleanup, or audit scripts — e.g., delete files older than X days using lastModified().

Gotchas and Tips

• Path traversal risk: Never pass untrusted input directly to methods like read() or write(); sanitize with realpath() or whitelist against a base path.
• Visibility defaults: write() uses Visibility::PUBLIC by default (e.g., 0644 on Unix), but directories default to 0755; override via the third argument: ['visibility' => Visibility::PRIVATE].
• Empty directories: write() auto-creates parent dirs, but createDir() is required to explicitly create empty folders (since they’re implicit on write).
• Path normalization: All internal paths use / as separator — avoid OS-specific assumptions (e.g., \ on Windows); Flysystem normalizes automatically.
• Symlink pitfalls: Relative symlinks resolve at runtime against the current working directory, not the adapter’s root — use absolute paths or verify behavior in CI/testing environments.
• Visibility maps: For granular permission control (e.g., umask-aware visibility), configure League\Flysystem\UnixVisibility\PermissionMap when constructing the adapter.