Files Laravel Package

Getting Started

Start by installing the package via Composer (composer require spiral/files) and examining the Spiral\Files\FilesInterface and Spiral\Files\IOException classes. The core functionality centers around the Files class, which provides atomic file operations (e.g., write(), append(), delete(), copy(), move()). The first practical use case is replacing standard PHP file functions with atomic alternatives to avoid partial writes or race conditions — e.g., write($path, $content) creates a temp file, writes to it, then renames atomically.

The package now adheres to PSR-12 coding standards, ensuring consistent code style and readability.

Implementation Patterns

• Atomic Writes: Use Files::write() instead of file_put_contents() for critical data (e.g., config snapshots, cache regeneration) to guarantee consistency.
• Virtual File Streams: Leverage Spiral\Files\Stream\Stream to abstract filesystem operations (e.g., mocking in tests via in-memory streams or testing S3 via PSR-18-compatible adapters).
• Directory Management: Combine getContents($dir), listFiles($dir), and removeDirectory($dir) for recursive operations.
• Testing: Inject FilesInterface (not concrete Files) to inject mock implementations in unit tests. Use Stream::factory('memory://') for zero-I/O test scenarios.
• Configuration: Configure root paths via Files::setRoot() or extend Files to set scoped roots per module (e.g., app/storage vs config/files).

Gotchas and Tips

• No Active Maintenance: Last update was in 2021 (v2.0.2); verify compatibility with modern PHP versions (tested up to PHP 8.x). Avoid in new projects unless embedded in Spiral Framework context.
• Error Handling: Always catch IOException — the component wraps low-level errors (e.g., permission denied, disk full) consistently.
• Path Normalization: Paths are canonicalized; avoid relative paths with .. to prevent unexpected behavior (use normalizePath() for safe inputs).
• Non-Recursive Operations: Methods like removeDirectory() only delete empty directories; use removeDirectory($dir, true) to force recursive removal.
• Stream Integration: When integrating with PSR-7/17, convert Stream to Psr\Http\Message\StreamInterface via stream_get_meta_data() and stream wrappers.
• Custom Adapters: Extend Spiral\Files\Files to inject custom logic (e.g., logging, metrics) in callMethod() — note that this component predates Laravel’s Filesystem enhancements, so consider using Laravel’s Storage for newer apps.
• PSR-12 Compliance: The package now follows PSR-12 standards, which may affect custom implementations or extensions that previously relied on non-standard formatting. Ensure your overrides or wrappers align with PSR-12 for consistency.