Class

CurlResponse

The PSR-7 response of an HttpClient request, filled in by a cURL transfer.

Introduction#

HttpClient::sendRequest returns a response whose headers have arrived. The convenience methods get(), post(), put() and request() return it before the transfer has started, so that several requests can run together: the first call that needs the status line or the headers (getStatusCode(), getHeader(), withHeader() and the like) or the first read of the body starts every pending transfer and waits for the headers, suspending only the calling coroutine. getBody() itself returns at once. Outside a coroutine that wait runs the transfers to the end. The body is read once: reading it again returns nothing.

A transfer that fails before the headers have arrived (connection refused, DNS failure, timeout, too many redirects, an invalid URL) throws from every accessor, and from the body read, a NetworkException, a RequestException or a ClientException, with cURL's error number as its code. A transfer that fails after the headers keeps its status, reason phrase and headers, and throws the exception when the body read reaches the point of the failure. A 4xx or 5xx status is not a failure.

The with*() methods wait for the headers and return a copy that shares the body stream.

Class synopsis#

class CurlResponse implements ResponseInterface, MessageInterface {
    /* Methods */
    public CurlResponse::withStatus(int $code, string $reasonPhrase = ''): ResponseInterface
    public CurlResponse::withProtocolVersion(string $version): MessageInterface
    public CurlResponse::withHeader(string $name, $value): MessageInterface
    public CurlResponse::withAddedHeader(string $name, $value): MessageInterface
    public CurlResponse::withoutHeader(string $name): MessageInterface
    public CurlResponse::withBody(StreamInterface $body): MessageInterface
    public CurlResponse::getProtocolVersion(): string
    public CurlResponse::getStatusCode(): int
    public CurlResponse::getReasonPhrase(): string
    public CurlResponse::hasHeader(string $name): bool
    public CurlResponse::getHeader(string $name): array
    public CurlResponse::getHeaderLine(string $name): string
    public CurlResponse::getHeaders(): array
    public CurlResponse::getBody(): StreamInterface
    public CurlResponse::getDownloadSize(): ?int
    public CurlResponse::getDownloadedBytes(): ?int
    public CurlResponse::getUploadSize(): ?int
    public CurlResponse::getUploaded(): ?int
}

Properties#

Name	Type	Description
`$options`	`readonly HttpClientOptions`
`$url`	`readonly string`
`$method`	`readonly string`

Methods#

Method	Description
`withStatus`	Return an instance with the specified status code and, optionally, reason phrase.
`withProtocolVersion`	Return an instance with the specified HTTP protocol version.
`withHeader`	Return an instance with the provided value replacing the specified header.
`withAddedHeader`	Return an instance with the specified header appended with the given value.
`withoutHeader`	Return an instance without the specified header.
`withBody`	Return an instance with the specified message body.
`getProtocolVersion`	Retrieves the HTTP protocol version as a string.
`getStatusCode`	Return the HTTP status code, waiting for the headers to arrive.
`getReasonPhrase`	Gets the response reason phrase associated with the status code.
`hasHeader`	Checks if a header exists by the given case-insensitive name.
`getHeader`	Retrieves a message header value by the given case-insensitive name.
`getHeaderLine`	Return the values of a header joined by ", ", or an empty string; the name is case-insensitive.
`getHeaders`	Retrieves all message header values.
`getBody`	Return the body stream, without waiting for the transfer.
`getDownloadSize`	Return the number of bytes cURL expects to download, or null before cURL has reported it.
`getDownloadedBytes`	Return the number of bytes downloaded so far, or null before cURL has reported any progress.
`getUploadSize`	Return the number of bytes cURL expects to upload, or null before cURL has reported it.
`getUploaded`	Return the number of bytes uploaded so far, or null before cURL has reported any progress.

Examples#

Example 1Read the body as it arrives

use phasync\HttpClient\HttpClient;

$base     = require __DIR__ . '/../server.php';
$response = (new HttpClient())->get("$base/stream");

echo get_class($response), "\n";
echo $response->getStatusCode(), "\n";   // waits for the headers only

$body = $response->getBody();
while (!$body->eof()) {
    $chunk = $body->read(1024);          // what has arrived so far
    if ('' !== $chunk) {
        echo 'read: ', json_encode($chunk), "\n";
    }
}
echo 'downloaded bytes: ', $response->getDownloadedBytes(), "\n";

Output

phasync\HttpClient\CurlResponse
200
read: "line 1\nline 2\nline 3\n"
downloaded bytes: 21

Example 2

$response = $client->get('https://example.com/report.csv');

if (200 === $response->getStatusCode()) {
    $body = $response->getBody();
    while (!$body->eof()) {
        echo $body->read(8192);
    }
}