Пакет · cast

Файлы

Большие тела не должны проходить через память. Cast пишет ответ прямо на диск и читает отправляемый файл с диска по частям.

Скачать в файл

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 — тело в файле
$response->getBody();       // поток над этим файлом

Только успешный ответ

В файл пишется только ответ 2xx. Ответ с ошибкой — например, 404 с JSON — остаётся в памяти, а файл не трогается:

php
$response = $client->get('exports/missing.csv')->sinkTo($path)->send();

$response->isSunk();        // false
$response->json();          // ['error' => 'not found']
// файл $path не создан и не изменён

Куда можно писать

Цель Как пишется getBody()
путь (строка) файл создаётся или перезаписывается поток над файлом
открытый ресурс с текущей позиции пустой поток: ресурс читаете вы
PSR-7 поток с текущей позиции этот же поток

Файл по пути открывается на первых байтах тела. Если передача оборвалась, недописанный файл удаляется. Если до тела дело не дошло, существующий файл остаётся как был.

Ограничение maxResponseSize на запись в файл не действует.

Докачка

Запись с текущей позиции позволяет докачать файл после обрыва. Откройте файл на дозапись и попросите у сервера остаток:

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)          // если файл на сервере сменился — придёт целиком
  ->sinkTo($file)
  ->withTimeouts(Timeouts::forDownload())
  ->send();

if ($response->getStatusCode() === 200 && $have > 0) {
  // сервер прислал файл целиком — начните заново с пустого файла
}
fclose($file);

206 Partial Content — обычный успешный ответ, он пишется в цель.

Прогресс

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: downloaded, downloadTotal, uploaded, uploadTotal (итог — null, пока неизвестен), downloadPercent() и uploadPercent(). Функция вызывается только при изменении чисел.

Отправить файл

php
$client->put('files/report.pdf')->withFileBody('/tmp/report.pdf', 'application/pdf')->send();

Файл читается с диска по частям и не загружается в память целиком. Content-Length берётся из размера файла. Так же отправляется любой поток: withBody(CastStream::fromFile($path)). Поток неизвестного размера уходит с Transfer-Encoding: chunked.

onProgress() работает и для отправки: uploaded и uploadPercent().

Форма с файлами

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')       // с диска, потоком
      ->withContent('note', 'текст из памяти', 'note.txt')             // строка как файл
      ->withStream('log', CastStream::fromFile('/var/log/app.log'), 'app.log'),
)->send();

То же массивом, как в PHP-формах: строки — поля, CURLFile и CURLStringFile — файлы.

php
$client->post('avatars')->withMultipartBody([
  'user' => '42',
  'image' => new CURLFile('/tmp/me.png', 'image/png', 'me.png'),
])->send();

Части с одинаковым именем (files[] дважды) тоже отправляются. cURL принимает поля массивом, где у ключа одно значение, поэтому такое тело собирается целиком и уходит потоком.