Temporary Directory

Spatie’s temporary-directory is a small, focused PHP package for creating, using, and cleaning up temporary directories in the system temp folder. It wraps the fiddly parts of scratch-directory management — naming, custom locations, permissions, path resolution, and recursive deletion — behind a fluent, chainable API.

With a single expression you can spin up a uniquely-named temporary directory, resolve paths to files inside it, empty it, or delete it entirely, and even have it removed automatically when the object goes out of scope. It has no runtime dependencies beyond PHP 8 and is used across the wider Spatie ecosystem for tests, dumps, and transient file processing.

What You Get

• A fluent TemporaryDirectory class with chainable create, name, location, permission, and force methods
• A static make() shortcut that constructs and creates a directory in one call
• Path resolution via path() that auto-creates nested subdirectories on demand
• Recursive deletion and empty() with a garbage-collection pass to avoid locked-file failures
• Automatic cleanup through deleteWhenDestroyed() tied to the object destructor

Common Use Cases

• Creating isolated scratch space for unit and integration tests
• Staging files during import/export, archiving, or media processing before moving them to permanent storage
• Generating transient dumps or intermediate build artifacts that must be cleaned up afterward

Under The Hood

Architecture The entire package is a single TemporaryDirectory class in src/TemporaryDirectory.php backed by two small exception types under src/Exceptions. Configuration methods (name, location, permission, force, deleteWhenDestroyed) each mutate internal state and return $this for chaining; create() resolves the target via getFullPath(), generates a random timestamped name when none is set, optionally force-deletes an existing directory, then mkdir()s recursively. Deletion is handled by a recursive deleteDirectory() that walks the tree with a FilesystemIterator and calls gc_collect_cycles() before rmdir() to release file handles.

Tech Stack Pure PHP 8 with zero runtime dependencies; the only require is php: ^8.0. Dev tooling is PHPUnit 9.5 for tests, php-cs-fixer for style, and GitHub Actions for CI. PSR-4 autoloading maps Spatie\TemporaryDirectory\ to src.

Code Quality The code is fully typed with property and return-type declarations, uses final on the constructor, and keeps helper logic (sanitizePath, sanitizeName, removeFilenameFromPath, isFilePath) in small protected methods. Invalid names throw InvalidDirectoryName and collisions throw PathAlreadyExists, giving clear failure modes. A dedicated tests directory with a PHPUnit config provides coverage.

API Design The fluent builder plus static make() shortcut makes the common path a single expression, and method names read like plain English (->name()->force()->create()). Path handling auto-creates intermediate directories so callers rarely deal with filesystem edge cases, and deleteWhenDestroyed() removes cleanup boilerplate entirely. The surface is tiny and self-explanatory, so onboarding is effectively instant for any PHP developer.