Weave Code
Filesystem Laravel Package
php-standard-library/filesystem
Type-safe filesystem helpers for PHP with consistent exception handling. Provides safer wrappers for common file and directory operations, aiming for clearer intent and fewer runtime surprises. Part of the PHP Standard Library ecosystem.
Type-safe functions for file system operations with proper exception handling
Frequently asked questions about Filesystem
- How does this package improve Laravel’s built-in Storage facade?
- It adds type safety and granular control (e.g., `Directory::ensure()` vs. `Storage::makeDirectory()`), plus consistent exception handling to catch issues like missing files early. Use it for local filesystem ops where Laravel’s Storage lacks precision, but avoid replacing cloud storage logic.
- Can I use this in Laravel’s HTTP controllers?
- No—stick to Laravel’s Storage facade for HTTP-bound workflows. This package is optimized for CLI tools, Artisan commands, and queue jobs where type safety and explicit error handling matter more.
- Will this work with Laravel 10+ and PHP 8.2?
- Yes, it supports PHP 8.1+ and Laravel 8.1+. While it aligns with Laravel’s minimum version, some PHP 8.2 features (like read-only properties) may not be leveraged yet. Always check the latest release notes for edge cases.
- How do I replace custom path helpers (e.g., `app/Helpers/PathHelper`)?
- Use the `PathResolver` class to standardize path construction across your app. Replace `base_path()`/`storage_path()` hacks with `PathResolver::resolve()` and deprecate legacy helpers incrementally.
- Does this support cloud storage like S3?
- No—it’s designed for local filesystem operations only. For cloud storage, continue using Laravel’s Storage facade or dedicated packages like `league/flysystem`. This package excels at local file ops with type safety.
- How do I handle exceptions in CLI tools?
- Wrap package exceptions (e.g., `FileNotFoundException`) in custom exceptions for consistency. Log unhandled exceptions in CLI tools using Laravel’s `Log::error()` or a dedicated error handler.
- Is the event system redundant with Laravel’s events?
- Yes, but only if used for business logic. Restrict `FilesystemEvent` to infrastructure tasks (e.g., logging, analytics) and bridge to Laravel events (e.g., `fileCreated → FileUploaded`) via listeners.
- How do I mock filesystem operations in unit tests?
- Use PHP’s `tmpfs` or mock the `FilesystemInterface` in tests. For example, replace `File::read()` with a mock that returns predefined content, or use Laravel’s `Storage::fake()` for hybrid testing.
- What’s the performance impact of `BatchProcessor`?
- It may introduce overhead for small datasets (<100 files). Benchmark against manual loops in queue workers, especially for bulk operations. For critical paths, profile with `laravel-debugbar` or Xdebug.
- Should I use this for production asset pipelines?
- No—it lacks cloud storage support. For production asset pipelines (e.g., uploading to S3), use Laravel’s Storage facade or a dedicated package like `spatie/laravel-medialibrary`. Reserve this for local filesystem tasks.
Weaver
How can I help you explore Laravel packages today?