Filesystem Laravel Package

Getting Started

Require the package via Composer (composer require illuminate/filesystem). Start with the core Filesystem class—no Laravel service container required. Perform basic operations like checking file existence and reading content:

use Illuminate\Filesystem\Filesystem;

$fs = new Filesystem();
if ($fs->exists('config/app.php')) {
    $content = $fs->get('config/app.php');
}

Focus first on the minimal surface area: exists(), get(), put(), delete(), copy(), move(). All methods throw Symfony\Component\Filesystem\Exception\IOException on failure, enabling consistent error handling.

Implementation Patterns

• Centralized File I/O: Replace raw file_get_contents()/file_put_contents() calls with Filesystem methods to enforce consistent error handling, path resolution, and exception handling.
• Deep Traversal with Iterators: Use allFiles($dir) or files($dir) (via Symfony Finder) to lazily iterate directory contents, handling SplFileInfo objects directly:

  foreach ($fs->files('lang') as $file) {
      $locale = $file->getPathInfo()->getFilename();
  }
  

• Atomic Writes for Reliability: Use atomicPut() for critical files (e.g., config, cache keys) to avoid partial writes during concurrent access.
• Dynamic Directory Creation: Call ensureDirectoryExists($path, 0755) before writing to new paths—handles recursive creation safely.
• Testing Isolation: Mock Filesystem directly in unit tests or leverage Laravel’s RefreshFilesystem trait in feature tests to avoid real filesystem interaction.
• Streaming Avoids Memory Bloat: For large files, pass a resource handle to put() or use readStream()/writeStream() (where available) instead of loading entire contents into memory.

Gotchas and Tips

• Path Resolution Is Critical: Always resolve relative paths using storage_path(), base_path(), or __DIR__. Relative paths behave differently in web vs CLI contexts (e.g., Artisan commands).
• Finder Returns SplFileInfo, Not Strings: files(), allFiles(), and directories() return SplFileInfo objects. Use $file->getPathname(), $file->getFilename()—not basename()—to extract values.
• Exception Type Matters: The thrown exception is Symfony\Component\Filesystem\Exception\IOException, not PHP’s generic Exception. Catch IOExceptionInterface appropriately.
• No Built-in File Locking: Filesystem doesn’t expose native flock() support. For locking, wrap fopen()/flock() manually or use Laravel’s Storage driver (e.g., local + flysystem’s lock plugin).
• Symlinks Have Platform Constraints: link() works only where symlinks are supported (e.g., not by default on Windows). Use $fs->link($target, $link) and test on target environments.
• Memory Use Isn’t Zero-Cost: allFiles() iterates efficiently but still loads metadata—avoid scanning large directories (e.g., /var/log) in long-running processes.
• Extend via Macros Judiciously: Use Filesystem::macro('jsonGet', ...) for project utilities, but prefer dedicated classes (e.g., JsonFileReader) for complex logic to avoid polluting core APIs.