Package · cast

Exceptions

All Cast exceptions live in Flytachi\Winter\Cast\Exception and implement Psr\Http\Client\ClientExceptionInterface.

Hierarchy

text
CastException                         RuntimeException, ClientExceptionInterface
├── RequestException                  the request cannot be sent      RequestExceptionInterface
├── NetworkException                  no response                     NetworkExceptionInterface
│   └── TimeoutException              a timeout or the deadline expired
├── TooLargeException                 body over maxResponseSize
├── HttpException                     4xx/5xx — only with throw() / withThrowOnError()
│   ├── ClientErrorException          4xx
│   └── ServerErrorException          5xx
└── BatchException                    sendAll(): some requests got no response

InvalidArgumentException              \InvalidArgumentException, ClientExceptionInterface

CastException

The root. catch (CastException $e) catches everything related to sending, except InvalidArgumentException. Thrown directly by:

  • jsonOrFail() — the body is not a JSON object or array;
  • MockTransport — no response left in the queue.

RequestException

The request cannot be sent. Implements PSR-18 RequestExceptionInterface.

When Message
the scheme is not http/https Only absolute http:// and https:// URLs can be sent
a relative path without a base URL … is not an absolute URL and the client has no base URL
more than max redirects Too many redirects (more than 10) from …
the sinkTo() file cannot be opened or written Cannot open the sink file … / Cannot write the response body …

getRequest() returns the request.

NetworkException

No response: DNS, connection refused, TLS, a dropped connection. Implements PSR-18 NetworkExceptionInterface.

Method Returns
getRequest() the request
getCurlErrno(): ?int the cURL error code (CURLE_*)
isTransient(): bool a retry may help — such errors are retried by RetryPolicy

Transient ones: could not connect (7), timed out (28), empty reply (52), send error (55) and receive error (56), partial body (18), HTTP/2 errors (16, 92). An unknown host and certificate errors are not transient.

TimeoutException

Extends NetworkException.

Method Returns
isConnect(): bool the connection was not established within connect
isDeadline(): bool the deadline of the whole operation ran out, not one attempt’s timeout
isTransient(): bool true, except for the deadline

The message for a stall timeout (idle) contains “Operation too slow”.

TooLargeException

The body in memory is larger than maxResponseSize. Thrown by Content-Length before downloading, or while receiving, as soon as the limit is exceeded.

Method Returns
getRequest() the request
getLimit(): int the limit in bytes

HttpException

A 4xx/5xx response — only from throw() or with withThrowOnError(). The class is chosen by the status.

Method Returns
getRequest() the request of the last attempt
getResponse(): CastResponse the response — the error body can be read
getStatusCode(): int the status
  • ClientErrorException — 4xx;
  • ServerErrorException — 5xx.

The message is “HTTP 404 Not Found: GET https://api.example.com/users/9”, the address without the query and user:password@.

BatchException

From sendAll() when some requests got no response. Thrown after all have finished.

Method Returns
responses(): array the responses received — under the requests’ keys
failures(): array request key ⇒ exception

getPrevious() is the first of the exceptions.

InvalidArgumentException

An invalid argument while building a request — before anything is sent:

  • a header: an empty or invalid name, \r, \n, NUL;
  • an invalid URI, port, method or response status;
  • data that cannot be encoded as JSON;
  • a reserved option in withCurlOptions();
  • an invalid settings argument: a negative size, a zero timeout, a sinkTo() target of the wrong type.

It extends the standard \InvalidArgumentException — PSR-7 requires that for the with*() methods — and implements ClientExceptionInterface.