In Laravel, why can Storage::put($path, file_get_contents($tmp)) exhaust memory on a 2 GB scan archive, and how do putFile, putFileAs and streams avoid it?

## Why the string version fails A clinic's nightly job zips the day's scanned referral letters into one archive and ships it to S3. The first version looks harmless: ```php Storage::disk('s3')->put('archives/2026-09-29.zip', file_get_contents($tmp)); ``` `file_get_contents()` returns a **PHP string** holding every byte of the file. A 2 GB archive therefore needs a 2 GB string in the process's memory, plus whatever the HTTP client copies while sending it. PHP enforces `memory_limit` per process, and a fatal "Allowed memory size exhausted" error kills the job. The same problem appears in reverse with `Storage::get()` on a large file. The fix is to hand Flysystem a **stream** (a PHP resource it can read in chunks) instead of a string. ## How put() decides between write and writeStream `FilesystemAdapter::put($path, $contents, $options = [])` inspects `$contents`: | `$contents` is | What Laravel does | |---|---| | `Illuminate\Http\File` or `UploadedFile` | delegates to `putFile($path, $contents, $options)` | | a PSR-7 `StreamInterface` | detaches it and calls `writeStream()` | | a PHP resource | calls `writeStream()` | | a string | calls `write()`, the whole string in memory | `$options` may be a visibility string (`'public'`/`'private'`) or an array of options. ## putFile and putFileAs `putFileAs($path, $file, $name, $options = [])`: 1. opens the file with `fopen(..., 'r')` (from a path string or the file object's real path); 2. calls `put("{$path}/{$name}", $stream, $options)`, which streams through `writeStream()`; 3. closes the stream; 4. returns the stored path, or `false` if the write failed. `putFile($path, $file, $options = [])` does the same with `$file->hashName()` as the name: 40 random characters plus an extension guessed from the file's MIME type. Store the returned path in the database; it is the only record of the generated name. A trap worth knowing: `put('archives/a.zip', new File($tmp))` goes through `putFile`, so it treats `archives/a.zip` as a **directory** and stores the file as `archives/a.zip/<random>.zip`. Use `putFileAs('archives', new File($tmp), 'a.zip')` when you want an exact name. ## Streaming between disks Reading from one disk and writing to another has the same choice: - **Avoid:** `Storage::disk('s3')->put($p, Storage::disk('local')->get($p))`, which pulls the whole file into memory. - **Manual streaming:** `$in = Storage::disk('local')->readStream($p); Storage::disk('s3')->writeStream($p, $in);` then close the handle. - **Built-in (Laravel 13.32+):** `Storage::disk('local')->copyToDisk('s3', $p)` streams from `readStream()` into the destination's `writeStream()` and closes the handle; `moveToDisk()` does the copy and then deletes the source only if the copy succeeded. Both accept a disk name or a filesystem instance, and an optional destination path. Within one disk, `copy()` and `move()` let the adapter do the work: on S3, Flysystem issues a server-side copy (and a delete for `move`), so no bytes pass through PHP at all. ## What streaming does not fix - **Time.** A 2 GB upload still takes as long as the network allows; run it in a queued job, not a web request. - **Temporary disk space.** The source file must exist somewhere readable while it streams. - **Reads.** `get()` and `json()` always return whole strings; use `readStream()` for large files. - **Remote read buffering.** Laravel's `s3` driver passes `stream_reads` as `false` unless the disk sets it, so large reads from S3 should enable `'stream_reads' => true`. ## Visibility and options on streamed writes The third argument works the same way on every write method: - a string such as `'public'` or `'private'` sets the stored file's visibility; - an array passes Flysystem options through, for example `['visibility' => 'private']` or a `mimetype` for the S3 adapter to use as the object's content type. For medical archives, leave visibility private and share them later with signed links. If the upload succeeds but setting visibility fails, `put()` treats that as a failure too: `UnableToSetVisibility` is caught alongside `UnableToWriteFile` and turns into `false` (or an exception with `throw` on). ## Checklist for large files 1. Accept files as `Illuminate\Http\File`, `UploadedFile` or resources, never as strings. 2. Use `putFileAs()` when the name matters and `putFile()` when a random name is fine. 3. Check the return value (a path or `false`) or enable `throw` on the disk. 4. Move files between disks with `copyToDisk()`/`moveToDisk()` or explicit streams. 5. Do the work in a queued job so request timeouts do not cut the transfer.