Weave Code
File Laravel Package
php-standard-library/file
Typed file handles for safe reading and writing in PHP, with explicit write modes and advisory file locking. Part of PHP Standard Library, designed to make filesystem IO clearer and less error-prone.
Typed file handles for reading and writing with write modes and advisory locking
Frequently asked questions about File
- How does this package improve Laravel’s built-in file handling for security-sensitive operations?
- The package adds `validateFileSignature()` to verify file integrity using checksums, which is critical for plugin uploads, executable files, or any workflow requiring cryptographic validation. Unlike Laravel’s native filesystem, it prevents tampered files from being processed, reducing security risks in production. It integrates seamlessly with Laravel’s Storage facade for hybrid workflows where local validation is needed alongside cloud storage.
- Can I use this package with Laravel’s Storage facade for atomic writes to config/cache files?
- Yes. The package’s `atomicWrite()` method ensures files are written entirely or not at all, preventing corruption during concurrent access. For Laravel, pair it with `storage_path()` or `config_path()` to handle local files atomically. This is especially useful for CLI jobs or queue workers modifying shared config files, where race conditions are a risk.
- What Laravel versions and PHP versions does this package support?
- The package requires **PHP 8.0+**, which aligns with Laravel 8.x and later. It’s framework-agnostic but designed to work alongside Laravel’s filesystem contracts. For older Laravel versions (7.x), you’d need to manually resolve path helpers like `storage_path()`, but the core functionality remains compatible. Always check the [latest release notes](https://github.com/php-standard-library/file/releases) for minor version updates.
- How do I integrate advisory file locking into a Laravel queue job?
- Use the `FileHandle` class with `lock()` to coordinate access to shared files across queue workers. For example, wrap a config file update in a `try-finally` block to release the lock. This prevents race conditions when multiple jobs attempt to modify the same file simultaneously. The package’s locking is advisory (not enforced by the OS), so it requires cooperative code.
- Does this package replace Laravel’s Filesystem contracts or Flysystem adapters?
- No. This package is for **local filesystem operations** where Laravel’s built-ins lack features like atomic writes or advisory locking. For cloud storage (S3, GCS), continue using Laravel’s `Storage` facade or Flysystem adapters. Use this package only for low-level, security-critical, or concurrent file operations on the local machine.
- What’s the performance impact of `validateFileSignature()` for large files?
- The method uses efficient hashing (SHA-256 by default) and streams file chunks to avoid loading entire files into memory. Benchmarks show minimal overhead for files under 100MB, but for larger files, consider async validation or caching signatures. For Laravel, cache validated signatures in the database or Redis to avoid repeated checks.
- How do I handle exceptions thrown by this package in a Laravel application?
- Exceptions like `InvalidSignatureException` or `FileLockException` can be mapped to Laravel’s `FilesystemException` for consistency. Use a try-catch block around file operations and log errors with Laravel’s logging system. For APIs, return HTTP 400/422 responses with descriptive messages. The package’s exceptions extend PHP’s native `RuntimeException`, making them easy to catch.
- Can I use this package for handling user uploads in Laravel?
- Yes, but focus on its security features like `validateFileSignature()` for critical uploads (e.g., plugins or executables). For general uploads, Laravel’s Filesystem or Flysystem may suffice. Store validated signatures in the database to track file integrity over time. Combine with Laravel’s validation rules for additional checks like file types or sizes.
- What are the alternatives to this package for file locking in Laravel?
- For advisory locking, alternatives include PHP’s `flock()` or third-party packages like `spatie/laravel-file-activity`. However, this package provides a higher-level abstraction with typed handles and write modes, reducing boilerplate. For OS-level locking (mandatory), use `flock()` directly, but it’s less portable. This package strikes a balance between safety and simplicity for Laravel applications.
- How do I test file operations with this package in Laravel’s testing environment?
- Use Laravel’s `Storage` facade to mock file paths and simulate edge cases like concurrent access or corrupted files. Test `validateFileSignature()` with both valid and tampered files, and verify exceptions are thrown as expected. For locking tests, use `FileHandle::lock()` in separate processes (e.g., with Laravel’s `Process` facade) to simulate race conditions. Always clean up test files afterward.
Weaver
How can I help you explore Laravel packages today?