Temporary Directory Laravel Package

Technical Evaluation

Architecture fit spatie/temporary-directory is a single-purpose, dependency-free utility class (PSR-4, no service provider, no config, no facade). That makes it framework-agnostic — it drops into Laravel, plain PHP services, and CLI workers identically. Its natural home in our architecture is the transient-artifact layer of jobs and pipelines: report/PDF generation, CSV imports and exports, media transcode staging, backup assembly, and test fixtures. It is a complement to Flysystem/Storage::disk(), not a replacement — anything that must survive the request or job belongs in object storage, and the TPM should hold that line explicitly so teams don't use this as a shadow persistence layer.

Integration feasibility Trivially high. One composer require, no migrations, no wiring, no bootstrapping. It can be adopted in a single small PR and reverted just as cleanly, which makes it a low-ceremony approval. The only real integration work is policy, not code: standardizing location, permissions, and cleanup guarantees behind a thin in-app wrapper.

Technical risk — low, but concentrated in one area: disk

• Ephemeral storage exhaustion. This is the primary production risk, not the library. Read-only root filesystems, tmpfs sized as a fraction of RAM, and capped emptyDir volumes in Kubernetes turn a "convenience" call into an ENOSPC outage under large payloads. Confirm scratch space per node before rollout.
• Orphaned directories. Cleanup relies on delete() or deleteWhenDestroyed(). Fatal errors, OOM kills, and job timeouts bypass both, leaving silent disk growth. This needs monitoring, not optimism.
• Permissions. Default 0777 will fail a security review; the now-configurable permission() must be mandated in our wrapper.
• Deterministic naming. name() + force() is a collision hazard in parallel queue workers; timestamped defaults are safe, explicit names are not.
• Container/Windows path semantics and cross-filesystem moves if staging and destination differ.

Key questions

1. What is the actual scratch-disk budget per pod/node, and what is the p95/p99 artifact size per job?
2. Do any of these artifacts contain PII or regulated data, and is there a documented wipe requirement beyond "the directory is deleted"?
3. What is our queue retry/timeout policy, and do we need cleanup to survive a hard worker kill?
4. Is there an internal owner for third-party libraries, or does this fall into a gap?
5. Which existing bespoke temp-dir code does this replace, and what's the blast radius of that consolidation?

Integration Approach

Stack fit Laravel 10–12 on PHP 8.1+, Composer-managed, already standardized on Spatie-adjacent packages. The package imposes no Laravel version constraint and pulls in no transitive dependencies, so it cannot drag in a version conflict. It slots in cleanly alongside Flysystem: temp dir for staging, storage disk for the durable copy.

Migration path Additive and incremental — no rewrite required.

• Replace ad-hoc tempnam(), sys_get_temp_dir() . uniqid(), hand-rolled recursive mkdir/rmdir, and mkdir/File::deleteDirectory() pairs with a single object that owns its own lifecycle.
• Introduce an app-namespaced wrapper (e.g., ScratchDirectory) that encodes our defaults — location, 0755, deleteWhenDestroyed(), and a try/finally contract — so application code never touches the vendor class directly. This keeps a future swap to a homegrown or alternative implementation to one file.
• Consolidate existing bespoke temp-dir helpers onto the wrapper rather than doing a find-and-replace.

Compatibility PHP 8.0+ required (v2 dropped 7.x); our floor exceeds that. MIT license — no legal review friction, compatible with commercial distribution. Changelog and releases are consistently maintained, including PHP 8.5 CI coverage. The metadata's "Dependents: 0" is almost certainly a data-collection artifact for a package with ~1k stars and heavy Packagist download volume; don't treat it as a signal either way, but do verify transitive adoption internally.

Sequencing

1. Spike in one non-critical job; measure artifact sizes and peak /tmp usage.
2. Standardize the wrapper and document the "staging vs. durable" rule in engineering standards.
3. Migrate high-volume file jobs first, in descending order of disk pressure.
4. Instrument — disk-usage metric, cleanup-failure counter, alert on orphaned-directory growth.
5. Enforce via PR template / static analysis rule banning raw tmp primitives.
6. Retire legacy temp-dir utilities.

Operational Impact

Maintenance Negligible. The codebase is small enough to read in one sitting, semver is respected, and 2.4.0's static return change is BC-safe. Pin with a caret constraint and let Dependabot drive upgrades; budget roughly one reviewer-hour per release. The realistic risk isn't churn — it's abandonment, and the single-class footprint makes forking or vendoring a same-day exercise.

Support Community-only via GitHub issues. No SLA, no vendor escalation path; Spatie's paid products are unrelated. Assign a named internal owner for the wrapper (not the vendor package) and treat upstream as best-effort. The tiny surface area means the wrapper is our real support boundary.

Scaling Scales horizontally with the application tier because the pressure point is node-local disk, not CPU or memory. Two scaling concerns to plan for: (1) containers with small or memory-backed scratch volumes fail hard on large artifacts, so add size-based routing — above a threshold, stream directly to object storage instead of staging; (2) per-node scratch is not shared, so any workflow assuming a temp dir survives across job steps is broken by design under horizontal scaling.

Failure modes

• ENOSPC mid-write → partial files, confusing exceptions, retries that re-consume the same disk.
• Permission denied under a non-root container user with a restrictive umask.
• Orphaned directories after OOM/timeout/kill -9 — the highest-likelihood silent failure, and the one most likely to page someone at 3 a.m.
• deleteWhenDestroyed() not firing on fatal shutdown, creating false confidence in code review.
• Log noise from delete exceptions on already-removed directories.
• Cross-filesystem rename failures when staging location and destination differ.

Ramp-up Near-zero. A short snippet in onboarding docs plus the staging-vs-durable rule is sufficient for any PHP developer. The only genuine training need is discipline: always pair creation with try/finally, prefer deleteWhenDestroyed() for scoped use, and recognize when the correct answer is object storage rather than a temp directory. That's a documentation task, not a training program.