Files
Large bodies should not pass through memory. Cast writes a response straight to disk and reads a file it sends from disk piece by piece.
Download to a file
use Flytachi\Winter\Cast\Client\Timeouts;
$response = $client->get('exports/2026-11.csv')
->sinkTo('/var/data/export.csv')
->withTimeouts(Timeouts::forDownload())
->send()
->throw();
$response->isSunk(); // true — the body is in the file
$response->getBody(); // a stream over that fileSuccessful responses only
Only a 2xx response is written to the file. An error response — say, a 404 with JSON — stays in memory, and the file is left alone:
$response = $client->get('exports/missing.csv')->sinkTo($path)->send();
$response->isSunk(); // false
$response->json(); // ['error' => 'not found']
// the file at $path was not created or changedWhere it can write
| Target | How it is written | getBody() |
|---|---|---|
| a path (string) | the file is created or overwritten | a stream over the file |
| an open resource | from the current position | an empty stream: you read the resource |
| a PSR-7 stream | from the current position | that same stream |
A file given by path is opened when the first bytes of the body arrive. If the transfer breaks off, the partly written file is removed. If the body never started, an existing file stays as it was.
maxResponseSize does not apply when writing to a file.
Resuming
Writing from the current position lets you resume a download after a break. Open the file for appending and ask the server for the rest:
$path = '/var/data/big.iso';
$have = is_file($path) ? filesize($path) : 0;
$file = fopen($path, 'ab');
$response = $client->get('files/big.iso')
->withHeader('Range', "bytes={$have}-")
->withHeader('If-Range', $etag) // if the file changed on the server, it comes whole
->sinkTo($file)
->withTimeouts(Timeouts::forDownload())
->send();
if ($response->getStatusCode() === 200 && $have > 0) {
// the server sent the whole file — start over with an empty file
}
fclose($file);206 Partial Content is an ordinary successful response and is written to the target.
Progress
use Flytachi\Winter\Cast\Message\TransferProgress;
$client->get('files/big.iso')
->sinkTo($path)
->onProgress(function (TransferProgress $p): void {
printf("\r%5.1f%%", $p->downloadPercent() ?? 0);
})
->send();TransferProgress has downloaded, downloadTotal, uploaded, uploadTotal (the totals are
null until known), downloadPercent() and uploadPercent(). The function is called only
when the numbers change.
Upload a file
$client->put('files/report.pdf')->withFileBody('/tmp/report.pdf', 'application/pdf')->send();The file is read from disk piece by piece and never loaded into memory whole. Content-Length
comes from the file size. Any stream is sent the same way:
withBody(CastStream::fromFile($path)). A stream of unknown size goes out with
Transfer-Encoding: chunked.
onProgress() works for uploads too: uploaded and uploadPercent().
Forms with files
use Flytachi\Winter\Cast\Message\CastStream;
use Flytachi\Winter\Cast\Message\Multipart;
$client->post('avatars')->withMultipartBody(
Multipart::create()
->withField('user', '42')
->withFile('image', '/tmp/me.png', 'me.png', 'image/png') // from disk, streamed
->withContent('note', 'text from memory', 'note.txt') // a string as a file
->withStream('log', CastStream::fromFile('/var/log/app.log'), 'app.log'),
)->send();The same as an array, the way PHP forms do it: strings are fields, CURLFile and
CURLStringFile are files.
$client->post('avatars')->withMultipartBody([
'user' => '42',
'image' => new CURLFile('/tmp/me.png', 'image/png', 'me.png'),
])->send();Parts that share a name (files[] twice) are sent too. cURL takes fields as an array, where a
key has one value, so such a body is rendered whole and sent as a stream.