Skip to content

Commit

Permalink
Add dedicated methods to control options, deprecate withOptions()
Browse files Browse the repository at this point in the history
  • Loading branch information
@clue
clue committed Jul 1, 2020
1 parent 5be8c54 commit d95302d
Show file tree
Hide file tree
Showing 5 changed files with 443 additions and 128 deletions.
200 changes: 163 additions & 37 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -61,10 +61,13 @@ mess with most of the low-level details.
* [requestStreaming()](#requeststreaming)
* [~~submit()~~](#submit)
* [~~send()~~](#send)
* [withOptions()](#withoptions)
* [withTimeout()](#withtimeout)
* [withFollowRedirects()](#withfollowredirects)
* [withRejectErrorResponse()](#withrejecterrorresponse)
* [withBase()](#withbase)
* [withoutBase()](#withoutbase)
* [withProtocolVersion()](#withprotocolversion)
* [~~withOptions()~~](#withoptions)
* [ResponseInterface](#responseinterface)
* [RequestInterface](#requestinterface)
* [UriInterface](#uriinterface)
Expand Down Expand Up @@ -211,23 +214,21 @@ response body and following any eventual [redirects](#redirects). See also
disable following redirects altogether) and also [streaming](#streaming-response)
below to not take receiving large response bodies into account for this timeout.

You can use the [`timeout` option](#withoptions) to pass a custom timeout value
in seconds like this:
You can use the [`withTimeout()` method](#withtimeout) to pass a custom timeout
value in seconds like this:

```php
$browser = $browser->withOptions(array(
'timeout' => 10.0
));
$browser = $browser->withTimeout(10.0);

$browser->get($url)->then(function (Psr\Http\Message\ResponseInterface $response) {
// response received within 10 seconds maximum
var_dump($response->getHeaders());
});
```

Similarly, you can use a negative timeout value to not apply a timeout at all
or use a `null` value to restore the default handling.
See also [`withOptions()`](#withoptions) for more details.
Similarly, you can use a bool `false` to not apply a timeout at all
or use a bool `true` value to restore the default handling.
See [`withTimeout()`](#withtimeout) for more details.

If you're using a [streaming response body](#streaming-response), the time it
takes to receive the response body stream will not be included in the timeout.
Expand Down Expand Up @@ -267,8 +268,8 @@ using the `Authorization: Basic …` request header or allows you to set an expl

By default, this library does not include an outgoing `Authorization` request
header. If the server requires authentication, if may return a `401` (Unauthorized)
status code which will reject the request by default (see also
[`obeySuccessCode` option](#withoptions) below).
status code which will reject the request by default (see also the
[`withRejectErrorResponse()` method](#withrejecterrorresponse) below).

In order to pass authentication details, you can simple pass the username and
password as part of the request URL like this:
Expand Down Expand Up @@ -329,23 +330,20 @@ possible privacy/security concerns. When following a redirect where the `Locatio
response header contains authentication details, these details will be sent for
following requests.

You can use the [`maxRedirects` option](#withoptions) to control the maximum
number of redirects to follow or the [`followRedirects` option](#withoptions)
to return any redirect responses as-is and apply custom redirection logic
like this:
You can use the [`withFollowRedirects()`](#withfollowredirects) method to
control the maximum number of redirects to follow or to return any redirect
responses as-is and apply custom redirection logic like this:

```php
$browser = $browser->withOptions(array(
'followRedirects' => false
));
$browser = $browser->withFollowRedirects(false);

$browser->get($url)->then(function (Psr\Http\Message\ResponseInterface $response) {
// any redirects will now end up here
var_dump($response->getHeaders());
});
```

See also [`withOptions()`](#withoptions) for more details.
See also [`withFollowRedirects()`](#withfollowredirects) for more details.

### Blocking

Expand Down Expand Up @@ -979,32 +977,129 @@ For an empty request body, if will only include a `Content-Length: 0`
request header if the request method usually expects a request body (only
applies to `POST`, `PUT` and `PATCH`).

#### withOptions()
#### withTimeout()

The `withOptions(array $options): Browser` method can be used to
change the options to use:
The `withTimeout(bool|number $timeout): Browser` method can be used to
change the maximum timeout used for waiting for pending requests.

The [`Browser`](#browser) class exposes several options for the handling of
HTTP transactions. These options resemble some of PHP's
[HTTP context options](https://www.php.net/manual/en/context.http.php) and
can be controlled via the following API (and their defaults):
You can pass in the number of seconds to use as a new timeout value:

```php
$newBrowser = $browser->withOptions(array(
'timeout' => null,
'followRedirects' => true,
'maxRedirects' => 10,
'obeySuccessCode' => true,
'streaming' => false, // deprecated, see requestStreaming() instead
));
$browser = $browser->withTimeout(10.0);
```

See also [timeouts](#timeouts), [redirects](#redirects) and
[streaming](#streaming-response) for more details.
You can pass in a bool `false` to disable any timeouts. In this case,
requests can stay pending forever:

```php
$browser = $browser->withTimeout(false);
```

You can pass in a bool `true` to re-enable default timeout handling. This
will respects PHP's `default_socket_timeout` setting (default 60s):

```php
$browser = $browser->withTimeout(true);
```

See also [timeouts](#timeouts) for more details about timeout handling.

Notice that the [`Browser`](#browser) is an immutable object, i.e. this
method actually returns a *new* [`Browser`](#browser) instance with the
options applied.
given timeout value applied.

#### withFollowRedirects()

The `withTimeout(bool|int $$followRedirects): Browser` method can be used to
change how HTTP redirects will be followed.

You can pass in the maximum number of redirects to follow:

```php
$new = $browser->withFollowRedirects(5);
```

The request will automatically be rejected when the number of redirects
is exceeded. You can pass in a `0` to reject the request for any
redirects encountered:

```php
$browser = $browser->withFollowRedirects(0);

$browser->get($url)->then(function (Psr\Http\Message\ResponseInterface $response) {
// only non-redirected responses will now end up here
var_dump($response->getHeaders());
});
```

You can pass in a bool `false` to disable following any redirects. In
this case, requests will resolve with the redirection response instead
of following the `Location` response header:

```php
$browser = $browser->withFollowRedirects(false);

$browser->get($url)->then(function (Psr\Http\Message\ResponseInterface $response) {
// any redirects will now end up here
var_dump($response->getHeaderLine('Location'));
});
```

You can pass in a bool `true` to re-enable default redirect handling.
This defaults to following a maximum of 10 redirects:

```php
$browser = $browser->withFollowRedirects(true);
```

See also [redirects](#redirects) for more details about redirect handling.

Notice that the [`Browser`](#browser) is an immutable object, i.e. this
method actually returns a *new* [`Browser`](#browser) instance with the
given redirect setting applied.

#### withRejectErrorResponse()

The `withRejectErrorResponse(bool $obeySuccessCode): Browser` method can be used to
change whether non-successful HTTP response status codes (4xx and 5xx) will be rejected.

You can pass in a bool `false` to disable rejecting incoming responses
that use a 4xx or 5xx response status code. In this case, requests will
resolve with the response message indicating an error condition:

```php
$browser = $browser->withRejectErrorResponse(false);

$browser->get($url)->then(function (Psr\Http\Message\ResponseInterface $response) {
// any HTTP response will now end up here
var_dump($response->getStatusCode(), $response->getReasonPhrase());
});
```

You can pass in a bool `true` to re-enable default status code handling.
This defaults to rejecting any response status codes in the 4xx or 5xx
range with a [`ResponseException`](#responseexception):

```php
$browser = $browser->withRejectErrorResponse(true);

$browser->get($url)->then(function (Psr\Http\Message\ResponseInterface $response) {
// any successful HTTP response will now end up here
var_dump($response->getStatusCode(), $response->getReasonPhrase());
}, function (Exception $e) {
if ($e instanceof Clue\React\Buzz\Message\ResponseException) {
// any HTTP response error message will now end up here
$response = $e->getResponse();
var_dump($response->getStatusCode(), $response->getReasonPhrase());
} else {
var_dump($e->getMessage());
}
});
```

Notice that the [`Browser`](#browser) is an immutable object, i.e. this
method actually returns a *new* [`Browser`](#browser) instance with the
given setting applied.

#### withBase()

Expand Down Expand Up @@ -1068,6 +1163,37 @@ Notice that the [`Browser`](#browser) is an immutable object, i.e. this
method actually returns a *new* [`Browser`](#browser) instance with the
new protocol version applied.

#### ~~withOptions()~~

> Deprecated since v2.9.0, see [`withTimeout()](#withtimeout), [`withFollowRedirects()`](#withfollowredirects)
and [`withRejectErrorResponse()`](#withrejecterrorresponse) instead.

The deprecated `withOptions(array $options): Browser` method can be used to
change the options to use:

The [`Browser`](#browser) class exposes several options for the handling of
HTTP transactions. These options resemble some of PHP's
[HTTP context options](https://www.php.net/manual/en/context.http.php) and
can be controlled via the following API (and their defaults):

```php
// deprecated
$newBrowser = $browser->withOptions(array(
'timeout' => null, // see withTimeout() instead
'followRedirects' => true, // see withFollowRedirects() instead
'maxRedirects' => 10, // see withFollowRedirects() instead
'obeySuccessCode' => true, // see withRejectErrorResponse() instead
'streaming' => false, // deprecated, see requestStreaming() instead
));
```

See also [timeouts](#timeouts), [redirects](#redirects) and
[streaming](#streaming-response) for more details.

Notice that the [`Browser`](#browser) is an immutable object, i.e. this
method actually returns a *new* [`Browser`](#browser) instance with the
options applied.

### ResponseInterface

The `Psr\Http\Message\ResponseInterface` represents the incoming response received from the [`Browser`](#browser).
Expand Down Expand Up @@ -1101,7 +1227,7 @@ This is a standard interface defined in
The `ResponseException` is an `Exception` sub-class that will be used to reject
a request promise if the remote server returns a non-success status code
(anything but 2xx or 3xx).
You can control this behavior via the ["obeySuccessCode" option](#withoptions).
You can control this behavior via the [`withRejectErrorResponse()` method](#withrejecterrorresponse).

The `getCode(): int` method can be used to
return the HTTP response status code.
Expand Down
Loading

0 comments on commit d95302d

Please sign in to comment.