Temporary Directory Laravel Package

Product Decisions This Supports

• Feature scoping for any "process a file" workflow. Exports (CSV/PDF/XLSX), image resizing, report generation, invoice rendering, bulk imports, archive creation, and media transcoding all need a scratch workspace that is guaranteed not to leak. This package makes "where does the intermediate file live, and who deletes it?" a one-line decision instead of a design debate.
• Build vs. buy. The honest comparison is "buy" against roughly 40–80 lines of tempnam/mkdir/FilesystemIterator glue. The package wins not on capability but on the long tail of edge cases you would otherwise rediscover in production: broken symlinks on delete, 0777 default permissions with an override, name collisions under concurrent load, and cleanup that survives exceptions. At ~zero cost and MIT license, buying the hardened version is the default-correct call.
• Roadmap enablement: moving work off the request cycle. Any plan to push heavy work into queued jobs, scheduled commands, or batch pipelines increases the number of places that write throwaway files to disk. Standardizing on one API now (create(), path(), delete()) prevents each team from inventing its own /tmp convention, which is a recurring source of "disk full at 3 a.m." incidents.
• Reliability and hygiene decisions. deleteWhenDestroyed() is the decision-relevant feature: it lets you make cleanup a property of scope rather than a step a developer must remember. That converts a class of bug (orphaned directories accumulating until the volume fills) into a code-review-level guarantee.
• Operational and cost decisions. Temporary local disk is materially cheaper than object storage for short-lived intermediates. Choosing this package is implicitly choosing "keep intermediates on the worker's disk, not in S3," which affects infrastructure sizing, worker ephemerality, and data-residency posture.
• Test-suite and DX decisions. Fixture generation, snapshot artifacts, and file-upload tests all need isolated directories. Adoption here lowers the cost of writing the file-touching tests that teams usually skip.
• Portability decisions. An explicit location() / constructor location argument plus configurable permission() means the same code works on a laptop, in a container with a read-only root, and on a mounted scratch volume — a decision that otherwise surfaces late, during deployment.
• Security/compliance posture. MIT license, no telemetry, no network calls, no external service. That keeps procurement and legal review to a minimum and avoids introducing a data-egress surface into a file-handling path.

When to Consider This Package

Adopt when most of the following hold:

• Your stack is PHP 8+ on Laravel/Symfony and you already pull Spatie packages; the dependency graph cost is effectively zero (this is a transitive dependency of several Spatie packages you likely already have, so it may already be installed).
• You have more than one or two places in the codebase that touch ephemeral files, or you are about to add the third.
• Your failures are leak-shaped: you have seen, or expect to see, workers filling disks, /tmp growing unbounded, or "works locally, fails in the container" cleanup bugs.
• Cleanup must be exception-safe and ideally scope-bound (deleteWhenDestroyed()), rather than dependent on a developer remembering a finally block.
• You need deterministic paths inside the workspace — path('dumps/datadump.dat') — for handing off to libraries that expect a filesystem path (DomPDF, Intervention Image, PhpSpreadsheet, ZipArchive).
• Compliance or procurement makes a small, auditable, MIT-licensed, network-free dependency preferable to a larger framework abstraction.

Look elsewhere when:

• You need distributed or multi-host coordination on the same scratch space — this is single-machine, local-filesystem only. Reach for object storage (S3, GCS) or a shared volume instead.
• The artifact is large or long-lived (gigabytes, or needed across job retries/hosts). Local temp directories and ephemeral workers are a poor match; a durable bucket with lifecycle rules is the right primitive.
• You need a full filesystem abstraction (copy, move, glob, mime detection, remote disks). Use league/flysystem or Laravel's Storage facade; this package is deliberately not that.
• Your runtime is serverless or read-only-root (e.g., some Lambda/Vercel-style setups) with limited or no writable /tmp. Verify the environment before committing; the location() option helps but does not create capacity.
• You need temp file semantics rather than temp directory semantics. tempnam() or Flysystem's temp-file helpers may fit better.
• The team already has a blessed internal filesystem utility. Adding a second convention costs more in consistency than it saves.
• Maintenance concentration is a hard blocker for you. This is a small package maintained by a single vendor; audit the bus factor against your dependency policy. In practice the surface area is so small that vendoring it is a viable fallback.

Migration/risk notes for the evaluation: the 2.0 release dropped PHP 7 and replaced generic exceptions with dedicated exception classes, so exception handling written against 1.x will silently change behavior. Pin the major version and check that no existing catch (InvalidArgumentException) blocks depend on the old contract. Also confirm your CI matrix matches the package's supported PHP versions.

How to Pitch It (Stakeholders)

For executives (30 seconds): We have several features that create throwaway files on disk — generated reports, exports, image processing, bulk imports. Today each one handles cleanup a little differently, and the failure mode is boring but expensive: disks fill up, workers fall over, and someone gets paged. This is a free, MIT-licensed utility from a well-established PHP vendor that makes creating and — critically — guaranteeing the deletion of that scratch space a one-liner. It is a small, low-risk standardization, not a platform bet. Expected outcome: fewer disk-related incidents, faster delivery on the next few file-handling features, and no new vendor, license, or data-handling exposure.

For engineering (the real argument): Stop hand-rolling temp-directory logic. The package gives you a scoped object with create(), path(), empty(), delete(), and — the reason to adopt — deleteWhenDestroyed(), so cleanup happens on scope exit rather than on developer discipline. It handles the parts your ad-hoc code forgets: recursive deletion, broken symlinks, unique directory names under concurrent load, configurable permissions (default 0777, override with permission()), and a custom base location for containerized environments where /tmp is constrained. It throws dedicated exceptions, so "directory already exists" is catchable and force() is an explicit opt-in rather than a race. It is PHP 8+, zero-config, network-free, and likely already in the dependency tree via other Spatie packages — meaning the marginal cost is close to zero. It is deliberately not a filesystem abstraction: it does one thing, so it will not compete with Storage or Flysystem or drag you into a rewrite.

What we are explicitly not claiming: this will not reduce infrastructure spend on its own, is not a substitute for object storage, and does not solve capacity planning. It removes a class of self-inflicted bugs and one recurring design argument. That is the whole pitch, and it is enough.