Weave Code
File Laravel Package
amphp/file
Non-blocking file I/O for PHP 8.1+ in the AMPHP ecosystem. Read/write files or stream via async file handles while keeping apps responsive. Uses multi-process by default, with optional eio/uv/parallel drivers when available.
An abstraction layer and non-blocking file access solution that keeps your application responsive.
Frequently asked questions about File
- Can I use amphp/file in Laravel for async file uploads without blocking the request?
- Yes, amphp/file is perfect for async file uploads in Laravel. Use it with spatie/laravel-amp or Swoole to offload file operations to a non-blocking event loop. Wrap the file handling in a fiber or promise and return a response immediately while the upload completes in the background. Ensure your event loop is active (e.g., via Amp\run() or Swoole’s reactor).
- How do I integrate amphp/file with Laravel’s Storage facade for async operations?
- Laravel’s Storage facade is synchronous, so you’ll need to create a custom async wrapper. Bind amphp/file’s File class to a service container interface (e.g., AsyncFilesystem) and use middleware or route groups to switch between sync and async modes. For example, in async routes, resolve the async filesystem and yield to the event loop during file operations.
- What’s the best driver to use for amphp/file in production if ext-eio or ext-uv aren’t available?
- If ext-eio or ext-uv aren’t available, fall back to the default multi-process driver or the blocking driver as a last resort. The blocking driver will work but defeats the purpose of non-blocking I/O. Configure the driver in your service provider based on environment variables or runtime checks, defaulting to the blocking driver with a warning log if needed.
- Will amphp/file work with Laravel’s queue system for processing large files asynchronously?
- Yes, amphp/file can complement Laravel queues by handling file operations within queue jobs. Use fibers or promises to avoid blocking the queue worker. For example, dispatch a job to process a file, then use Amp\File\read() or Amp\File\openFile() inside the job’s handle() method. Ensure your queue worker runs an event loop (e.g., via spatie/laravel-amp).
- How do I test amphp/file in Laravel’s PHPUnit tests without blocking the test runner?
- Test amphp/file operations by mocking the event loop or using in-memory files (e.g., tmpfs). For fiber-based tests, use PHPUnit’s data providers to test both sync and async paths. Leverage spatie/laravel-async or similar packages for testing async middleware. Avoid actual file I/O in tests; instead, mock Amp\File\read() or Amp\File\write() with in-memory streams or interfaces.
- Is amphp/file compatible with Laravel’s caching system for async file-based cache drivers?
- While amphp/file itself doesn’t integrate directly with Laravel’s cache, you can use it to build a custom async file-based cache driver. Replace blocking file operations (e.g., file_put_contents) with Amp\File\write() and Amp\File\read(). Ensure proper locking (e.g., file locking or database locks) to avoid race conditions between concurrent requests.
- What’s the performance difference between amphp/file and Laravel’s default Storage facade for reading large files?
- amphp/file can significantly outperform Laravel’s sync Storage facade for large files in concurrent environments due to non-blocking I/O. Benchmarks show throughput improvements of 2–10x in high-concurrency scenarios (e.g., 100+ concurrent requests). However, for single-threaded or low-concurrency apps, the overhead of async I/O may negate benefits. Test with your workload to determine the optimal approach.
- Can I use amphp/file with Laravel’s filesystem disk drivers (e.g., S3, local) for async operations?
- amphp/file is designed for local filesystem operations and doesn’t natively support cloud storage like S3. For async S3 operations, use Laravel’s queue system with AWS SDK v3’s async clients (e.g., Aws\S3\S3Client with promises). For local files, amphp/file is ideal—replace Storage::disk()->read() with Amp\File\read() in async contexts.
- How do I handle cancellation or timeouts when using amphp/file in Laravel?
- Use Amp\CancellationToken to handle timeouts or cancellations. For example, pass a token to Amp\File\read() and check for cancellation during long operations. In Laravel, integrate with middleware to cancel pending file operations if the request times out. Map Amp\PendingOperationError to Laravel’s HttpException or Throwable in your exception handler.
- Are there any known issues with file locking when using amphp/file in a multi-process Laravel environment?
- File locking can be tricky with amphp/file due to its multi-process or threading model. Use platform-specific locking (e.g., flock() on Unix) or database-backed locks for critical sections. Avoid relying solely on amphp/file’s file handles for synchronization. Test thoroughly in your deployment environment, as locking behavior may vary between ext-eio, ext-uv, and the default multi-process driver.
Weaver
How can I help you explore Laravel packages today?