Package · cast

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

php
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 file

Successful 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:

php
$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 changed

Where 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:

php
$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

php
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

php
$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

php
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.

php
$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.