Laravel Browsershot Laravel Package

Getting Started

v1.1.1 is a small additive patch: it adds a getTempFilePath() method. Nothing is removed or renamed, so upgrading from v1.1.0 is a drop-in composer update. The new method exposes the absolute, on-disk path of the temporary file the package has already materialised for you — the missing link whenever you need to hand that file to something that only speaks filenames rather than Laravel's UploadedFile/Storage abstractions.

Minimal steps:

1. composer require <vendor>/<package> "^1.1" (or bump the constraint) and confirm composer show <vendor>/<package> reports 1.1.1.
2. Check config/<package>.php after php artisan vendor:publish --tag=<package>-config — look for the temp/disk/working-directory keys, because that is where the path returned by getTempFilePath() actually points.
3. Read the package's README section on file lifecycle (creation → consumption → cleanup) before writing code. The method is only meaningful once you know who deletes the file and when.
4. First use case to try: generate an artifact, then stream it back to the user in a controller.

public function download(ExportRequest $request)
{
    $file = Exporter::make($request->validated())->generate();

    return response()
        ->download($file->getTempFilePath(), 'export.csv')
        ->deleteFileAfterSend(true);
}

The alternative — Storage::disk(...)->download(...) — requires the file to live on a configured disk. getTempFilePath() covers the case where it deliberately does not.

Implementation Patterns

Bridging to CLI tools. The primary reason this method exists is Symfony\Component\Process. Anything that shells out (ffmpeg, ImageMagick, Ghostscript, wkhtmltopdf, pdftk) wants a path, not a stream.

$result = Process::timeout(120)->run([
    'ffmpeg', '-i', $video->getTempFilePath(), '-vf', 'scale=1280:-2', $out = storage_path('app/out.mp4'),
]);

$result->throw();

Attaching to mail. $message->attach($path) needs a real path. Inline attachments in particular want attachFromStorage or a path; getTempFilePath() avoids bouncing through a disk.

Mail::to($user)->send(new ReportMail($report->getTempFilePath()));

Serving without a disk. response()->file($path) for inline previews (PDFs, images) and response()->download($path, $name) for downloads. Pair with deleteFileAfterSend(true) when the file is single-use.

Copy out before queueing. If the value is produced inside a request and consumed by a job, do not pass the path across the boundary. Copy first:

$durable = Storage::disk('s3')->putFileAs('reports', $file->getTempFilePath(), "{$id}.pdf");
dispatch(new ProcessReport($durable));

Chunked upload assembly. If the package handles concatenating parts, getTempFilePath() lets you hand the assembled file to a virus scanner (clamdscan $path), a hashing step (hash_file('sha256', $path)), or mime sniffing ((new MimeType())->from($path)) without re-reading it into memory.

Testing. Assert on the path, not on disk fakes — a temp path will not be intercepted by Storage::fake().

$file = Exporter::make($data)->generate();

$this->assertFileExists($file->getTempFilePath());
$this->assertSame('text/csv', mime_content_type($file->getTempFilePath()));

Gotchas and Tips

• The path is ephemeral by contract. It is valid only while the object that owns it is alive (and only within the process/machine that produced it). Never persist it in the database, never put it in a queued payload, never return it in an API response.
• "Temp" does not mean storage/app. It may well be sys_get_temp_dir() (/tmp, /var/folders/... on macOS). That means it is not covered by storage:link, not cleaned by php artisan storage:link/queue:clear, and not part of your normal backup set.
• Storage::fake() will not help you here. If a test asserts on getTempFilePath() under a faked disk, you will get a real path and confusing results. Use assertFileExists / assertFileDoesNotExist instead, or inject a configurable temp directory in tests.
• Cross-user temp isolation is the classic footgun. Your web requests run as www-data; your queue worker may run as www-data too — but with systemd's PrivateTmp=true, each service gets its own /tmp. If the file is created in the request and consumed in a job on the same machine, it can simply not be there. Check the unit file before debugging anything else.
• open_basedir and PrivateTmp both cause "file not found" on a file you just created. Log the actual path and ls -l it as the running user (sudo -u www-data ls -l /path) before assuming a package bug.
• Windows: spaces and backslashes. Always pass the path as an array element to Process; never interpolate it into a shell string. Wrap in quotes and you will be chasing phantom failures on filenames with spaces.
• File handles block deletion on Windows. If a process still holds the handle, unlink fails silently or throws. Close Process results and any fopen/SplFileObject before cleanup.
• Double deletion. If the package already deletes the temp file on destruct or on __destruct/cleanup, adding deleteFileAfterSend(true) or your own unlink is usually harmless (guarded by file_exists) but can throw in packages that are not guarded. Pick one owner of the file's lifetime and stick to it.
• Long-lived Horizon/RoadRunner workers accumulate temp files. The working directory is not swept automatically. Add a scheduled prune of the package's temp directory if you generate files at volume, and set a sensible lifetime in config.
• Debugging checklist. dump($file->getTempFilePath()), confirm existence with file_exists(), confirm size with filesize(), run realpath() to catch symlinked /tmp (common on macOS, where /tmp → /private/tmp, which breaks naive string comparisons in assertions).
• Extension points. Config for the temp directory is the lever for all of the above: pointing it at a shared, durable location (e.g. storage/app/tmp) solves the multi-service visibility problem without code changes, at the cost of managing cleanup yourself.