File Laravel Package

Product Decisions This Supports

• Feature feasibility for concurrent file I/O. amphp/file answers a specific question: can we do file reads, writes, streaming, and metadata checks without blocking the event loop? If any planned feature touches disk inside a long-running worker (Laravel Octane, RoadRunner, Swoole, or a native Amp/Revolt service), this package is the reference implementation to evaluate against.
• Roadmap sequencing for throughput-sensitive work. It directly informs prioritization of features like bulk export/import, media ingestion pipelines, log tailing, on-demand report generation, and large attachment streaming. If those are on the roadmap, non-blocking disk access is an enabling dependency, not a nice-to-have.
• Build vs. buy. The alternative to adopting this is writing a driver layer over ext-eio / ext-uv / ext-parallel plus a fallback process-pool implementation, and maintaining it. That is weeks of specialist work plus ongoing PHP-version upkeep. MIT-licensed, composer require-able, semver-managed, and abstracted behind a FilesystemDriver interface — the build case is weak.
• Architecture standardization. The driver abstraction (BlockingFilesystemDriver, ParallelFilesystemDriver, EioFilesystemDriver, UvFilesystemDriver, plus FileCache and status caching) lets us make one platform decision — "how does this service touch the disk?" — and apply it consistently, rather than every team hand-rolling file_get_contents inside fibers.
• Concurrency-safety decisions. The 4.x File::lock() / tryLock() / unlock() additions plus FileMutex and KeyedFileMutex let us decide, at design time, whether we need cross-process file locking primitives or whether the database is the correct coordination layer. That is a product-visible decision (e.g., duplicate export jobs, racing cache warmers).
• Use cases this unlocks: streaming large files to HTTP responses without buffering whole payloads in memory; parallel ingestion of uploaded assets; non-blocking reads for config/template/asset hot-reload in worker processes; directory scans and metadata sweeps for housekeeping jobs; safe append-only writers using file locks.
• Decisions this does not support. It is not a storage abstraction. It will not give us S3, GCS, or multi-tenant disk semantics — that remains Flysystem's job. It also does nothing for classic PHP-FPM request lifecycles, where blocking I/O is already isolated per request. Do not let it be framed as a general Laravel filesystem upgrade.

When to Consider This Package

Consider adoption when all or most of these hold:

• The runtime is genuinely concurrent and long-lived: Laravel Octane with a persistent worker, an Amp/Revolt service, RoadRunner, Swoole, or a queue worker processing many jobs per process.
• File operations are on the hot path or in loops — per-request attachment handling, batched document processing, recursive directory traversal, log shipping.
• You are already in, or deliberately entering, the AMPHP ecosystem (amphp/byte-stream, amphp/http-server, Revolt). Here it is essentially free: fibers mean the API reads like the blocking one (Amp\File\read() returns a string, not a promise).
• You need streaming file handles rather than whole-file loads, and you want the same interface across read/write/seek/truncate/eof.
• You need non-blocking advisory locking across processes (File::lock, tryLock, FileMutex, KeyedFileMutex) for job deduplication or serialized writes.
• PHP 8.1+ is guaranteed and a multi-process fallback is acceptable — the package works with zero extensions, spawning worker processes by default, and transparently upgrades to eio/uv/parallel when present.

Look elsewhere when:

• The application is a conventional PHP-FPM Laravel app. Blocking Storage:: calls are fine; adding an event loop to gain async file I/O is a net complexity increase with no user-visible benefit.
• You need a storage abstraction over local, S3, SFTP, or cloud disks. Use Flysystem / Laravel's Storage facade. The pragmatic pattern is Storage for abstraction, amphp/file only as a low-level driver for local disk inside async workers.
• The operations are rare, small, and cold (a settings JSON read at boot). The concurrency machinery costs more than it saves.
• Team familiarity with fibers, event loops, and cancellation semantics is low and there is no appetite to build it. Deadlocks and "why is my event loop stalled" incidents are the failure mode.
• You need vendor-backed support, SLAs, or a large hiring pool. At ~110 stars and 0 dependents, this is a specialist dependency with a small maintainer base — a real concentration risk to name explicitly.
• You require long-term API stability guarantees beyond semver. The 3.x → 4.x upgrade touched the File interface and driver constructors; anything implementing custom File classes or configuring ParallelFilesystemDriver worker counts breaks.

Adoption gate: pilot it in exactly one async worker path with a measurable baseline (p95 latency, event-loop stall count, memory peak), and pin the major version.

How to Pitch It (Stakeholders)

For executives (one paragraph): We have a small, low-cost engineering decision to make about how our long-running PHP services touch the disk. Today, file reads and writes inside our worker processes block the process entirely, so one slow upload or large export stalls every other request that worker is handling. amphp/file is a mature, MIT-licensed, actively maintained library that makes those operations non-blocking with a near-identical API. It is not a platform bet — it is a drop-in for one specific failure mode, requires no paid license and no new infrastructure, and can be trialed in a single service before any broader commitment. The risk to manage is dependency concentration: it is a specialist library with a small maintainer base, so we should pin versions and keep the blast radius to the async services that actually benefit.

For engineering leads:

• Problem it solves: blocking filesystem calls inside fibers/event loops serialize concurrency. This package provides a non-blocking driver layer with streaming file handles, metadata queries, directory operations, symlink handling, and — new in 4.x — non-blocking shared/exclusive locks.
• API ergonomics: Amp v3 + Revolt means fibers, not promises. Amp\File\read($path) returns the file contents directly; the blocking-looking code is the async code. Onboarding cost is understanding the event loop, not learning a new API surface.
• Zero-extension baseline: works out of the box using a multi-process driver, and automatically uses ext-eio, ext-uv, or ext-parallel when installed. That means we can ship without changing our PHP build, and improve performance later as an ops decision rather than a code change.
• Integration reality in Laravel: this is not a Laravel package. Laravel's Storage/Flysystem stack is blocking and stays that way. The realistic pattern is: keep Storage as the abstraction for feature code and cloud disks; use amphp/file as the local-disk implementation only inside Octane/Amp worker paths where the event loop is already running. Do not introduce it into FPM request handlers.
• Trade-offs to accept: small community (~110 stars, 0 dependent packages), so we own our integration risk; the 4.x interface change means custom File implementations are a real upgrade cost; and misuse outside an event loop yields no benefit at all. Mitigations: pin the major, isolate usage behind our own thin adapter so the dependency stays swappable, and benchmark before/after rather than assuming.
• Ask: approve a timeboxed pilot in one async worker path, with a go/no-go on measured p95 latency and event-loop stall reduction.