Download the PHP package edram/laravel-temp-workspace without Composer

Laravel Temp Workspace

English · 简体中文

Temporary, isolated workspaces backed by Laravel Storage, with automatic cleanup at the end of a request, command, or queue job attempt.

• Use familiar Storage methods: put(), get(), path(), readStream(), and more.
• Define a named workspace or pass a closure, with Laravel container injection.
• Return your result directly from handle() or the closure.
• Release additional resources through lifecycle hooks before files are deleted.

Contents

• Requirements
• Installation
• Basic usage
• Usage
  • Named workspaces
  • Anonymous workspaces
  • Temporary directory only
• Storage and configuration
• Lifecycle and cleanup
  • Named hooks
  • Terminating callbacks
  • Manual cleanup
• API reference
• Development
• License

Requirements

Installation

Laravel discovers the service provider automatically. Configuration is optional; workspaces use Laravel's default filesystem disk and the temporary-workspaces directory.

Basic usage

Use create() to get an isolated temporary directory and work with it through Laravel Storage methods:

Manual deletion is optional. At the end of the request, command, or queue job attempt, the package automatically removes the workspace directory and its contents.

Usage

Named workspaces

Create a class in app/TempWorkspaces. Put input values in the constructor and declare service dependencies on handle(), like a Laravel job or command.

For example, download a file and return its MD5 checksum:

Perform it through the manager:

The handle() return value is the result. Each instance has a stable ID that can be read before execution, and can only be prepared once. Create a new instance for each execution or retry.

Anonymous workspaces

Closures can receive both the current workspace and other container dependencies:

Temporary directory only

Use create() when you want to perform file operations directly:

Automatic cleanup also applies to workspaces created this way.

Storage and configuration

Optionally publish config/laravel-temp-workspace.php:

The disk defaults to null, so Laravel Storage resolves filesystems.default (configured by Laravel's FILESYSTEM_DISK). Set a workspace disk only when it should differ from the application's default.

Optional environment overrides:

Leave TEMP_WORKSPACE_DISK unset to follow Laravel's default disk. directory is relative to the disk; it is not an absolute filesystem path.

Each workspace is stored at temporary-workspaces/{id} relative to the selected disk. Workspace disks use Laravel's scoped driver and preserve the parent disk's prefix and options. Storage::fake() is supported for testing.

TempWorkspace forwards filesystem methods to its isolated disk. Access the underlying Laravel FilesystemAdapter through $workspace->disk().

On a local disk, path() returns a local filesystem path. On a remote disk, it returns a storage path; use get(), readStream(), or checksum() to process the file through Storage. URL methods depend on the selected driver's capabilities.

Preserve outputs before cleanup. If your result refers to a temporary file, copy or stream it to permanent storage before the workspace's lifecycle ends.

Lifecycle and cleanup

Nested command and job scopes clean their own workspaces, preserving those owned by the enclosing lifecycle. perform() itself does not trigger cleanup.

Cleanup relies on Laravel reaching its lifecycle events. Forced process termination and worker timeouts may leave files behind.

Named hooks

Add these methods to a named workspace as needed:

failed() receives the exception thrown by handle(). terminate() runs at cleanup before the directory is deleted, so it can still access the files and release additional resources. Dependencies on terminate() are container-resolved.

Terminating callbacks

Register additional cleanup from within your work or on a created workspace:

Callbacks run through the container after terminate() and before directory deletion. A failing hook does not prevent remaining hooks or cleanup from running. Hook and directory cleanup errors are reported through Laravel's exception handler. If failed() throws, the original work exception is still rethrown.

Manual cleanup

Call $workspace->destroy() to delete a single workspace's directory and contents immediately. It returns a boolean and only deletes files; lifecycle hooks still run when the manager cleans up, so those hooks should not rely on deleted files.

For long-running work, consume or persist the results, then explicitly clean all workspaces currently tracked by the manager:

Cleanup affects every scope tracked by that manager. Repeated calls without new workspaces do not rerun the completed cleanup hooks.

API reference

Resolve WorkspaceManager through the container, or call create(), perform(), and cleanup() through the LaravelTempWorkspace facade.

Development

Tests use Pest and Orchestra Testbench, including HTTP, Artisan, and synchronous and database queue lifecycle coverage.

License

MIT. See LICENSE.md.