Файлы
Большие тела не должны проходить через память. Cast пишет ответ прямо на диск и читает отправляемый файл с диска по частям.
Скачать в файл
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 — остаётся в памяти, а файл не трогается:
$response = $client->get('exports/missing.csv')->sinkTo($path)->send();
$response->isSunk(); // false
$response->json(); // ['error' => 'not found']
// файл $path не создан и не изменёнКуда можно писать
| Цель | Как пишется | getBody() |
|---|---|---|
| путь (строка) | файл создаётся или перезаписывается | поток над файлом |
| открытый ресурс | с текущей позиции | пустой поток: ресурс читаете вы |
| PSR-7 поток | с текущей позиции | этот же поток |
Файл по пути открывается на первых байтах тела. Если передача оборвалась, недописанный файл удаляется. Если до тела дело не дошло, существующий файл остаётся как был.
Ограничение maxResponseSize на запись в файл не действует.
Докачка
Запись с текущей позиции позволяет докачать файл после обрыва. Откройте файл на дозапись и попросите у сервера остаток:
$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 — обычный успешный ответ, он пишется в цель.
Прогресс
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(). Функция вызывается только
при изменении чисел.
Отправить файл
$client->put('files/report.pdf')->withFileBody('/tmp/report.pdf', 'application/pdf')->send();Файл читается с диска по частям и не загружается в память целиком. Content-Length берётся
из размера файла. Так же отправляется любой поток: withBody(CastStream::fromFile($path)).
Поток неизвестного размера уходит с Transfer-Encoding: chunked.
onProgress() работает и для отправки: uploaded и uploadPercent().
Форма с файлами
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 — файлы.
$client->post('avatars')->withMultipartBody([
'user' => '42',
'image' => new CURLFile('/tmp/me.png', 'image/png', 'me.png'),
])->send();Части с одинаковым именем (files[] дважды) тоже отправляются. cURL принимает поля
массивом, где у ключа одно значение, поэтому такое тело собирается целиком и уходит
потоком.