Safe Stream Laravel Package

Product Decisions This Supports

• Build vs. buy for a small reliability primitive. Atomic file writes (temp file + rename) are ~50 lines of subtle code that every team eventually writes badly. Adopting this package answers "do we build our own atomic-write helper?" with "no, spend that sprint on the roadmap."
• Reliability investment sizing. If your product writes anything a user or another process later reads — generated reports/exports, uploaded-file staging, file-based cache, queue spool files, config or manifest rewrites, cron output — you have a class of bugs where a crash or concurrent read yields a truncated or half-written file. This is a cheap mitigation for a support-ticket-generating failure mode.
• Infrastructure deferral. It lets you keep small artifacts on local disk safely instead of standing up Redis/S3/DB just to avoid corruption. That's a real cost decision for low-traffic or cost-sensitive tiers and for shared-hosting/on-prem deployments where you don't control the stack.
• Scope discipline on the roadmap. This is not a filesystem abstraction, object-storage layer, or locking framework. Framing it that way keeps it out of architectural debates it doesn't belong in, and keeps the adoption ticket small.
• Risk register entries. Two blockers to resolve as decisions, not surprises: (1) license is reported as NOASSERTION — legal must confirm terms before it ships in a commercial product; (2) provenance is unverified (repository unknown in this data), so pin a version and review the source before merge.

When to Consider This Package

Adopt when most of these are true:

• You write files from PHP that other processes read concurrently (PHP-FPM workers, cron jobs, queue workers, containers sharing a volume).
• You want atomicity without new infrastructure — no Redis, no S3, no DB.
• Your write payloads are small to moderate and not throughput-critical (the temp-file-then-rename pattern roughly doubles write I/O and transiently doubles disk usage).
• You're on Linux/Unix local disk, where rename() over an existing file is atomic.
• You need a one-line change at the call site — it's a stream wrapper, so file_put_contents('safe://…') and friends keep working.

Look elsewhere when:

• You need distributed locking or coordination — use Redis/DB locks; this doesn't do that.
• Your durability requirement is crash-consistent across power loss — rename gives atomicity of metadata, not fsync-backed durability of contents. Wrong tool.
• You're on object storage — S3-style PUTs are already atomic per object; the wrapper adds nothing.
• You're on NFS or Windows, where rename-over-existing and atomicity semantics differ and need explicit validation, not assumption.
• You're streaming large files or writing at high volume — the copy-then-rename overhead is a real regression.
• You want a actively staffed dependency: 118 stars and single-vendor (Nette) provenance means low bus factor. Mitigate by vendoring or forking if it becomes load-bearing, or by keeping the usage surface to a handful of call sites so it stays replaceable.

How to Pitch It (Stakeholders)

For executives (one paragraph): We have a recurring class of bug where a file is read while it's still being written, or a process dies mid-write, and the user sees a corrupted or empty file. This package makes those writes atomic with a one-line change at the call site and no new infrastructure cost. It's a small, mature, single-purpose open-source utility — low integration cost, low operational overhead, and it removes a support-ticket category rather than adding a system to run. Two things need sign-off before we ship it: a legal check on the license, and a source review of the pinned version.

For engineering: It's a PHP stream wrapper (safe://) that routes native fopen/file_get_contents/file_put_contents/unlink calls through atomic write semantics — write to a temp file, then rename into place, so readers never observe a partial file and a crash can't leave a truncated artifact. It is deliberately narrow: no locking, no fsync guarantees, no abstraction over disks. Treat it as a drop-in at specific call sites, not a global filesystem layer. Note it does not integrate automatically with Laravel's Storage/Flysystem facade — using it means calling native functions against a safe:// path (or wrapping it in a custom adapter), so scope the integration explicitly rather than assuming Storage::put gets safer for free.

Knowns and unknowns to state up front: license unresolved (NOASSERTION), provenance unverified in this dataset, low star count / single maintainer, and filesystem-behavior dependencies (Linux local disk yes; NFS/Windows need testing). All are manageable for a small, pinned, well-reviewed dependency — but they should be decisions we make, not assumptions we inherit.