Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add dedicated methods to control options, deprecate withOptions() #172

Merged
merged 2 commits into from
Jul 2, 2020
+447 −82
Merged

Add dedicated methods to control options, deprecate withOptions() #172

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
5be8c54
Add dedicated with* options methods in favour over withOptions
WyriHaximus Mar 12, 2020
4d3ea44
Add dedicated methods to control options, deprecate `withOptions()`
clue Jun 30, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
200 changes: 163 additions & 37 deletions README.md
View file
Open in desktop
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