From 04fefce7ed3708227194553088cb3cf70f786f97 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20L=C3=BCck?= Date: Wed, 1 Jul 2020 23:13:48 +0200 Subject: [PATCH] Deprecate `UriInterface` for request methods, use URL strings instead --- README.md | 36 ++++++++++++++++++++++++++++++++++++ src/Browser.php | 32 ++++++++++++++++++++++++++++++++ 2 files changed, 68 insertions(+) diff --git a/README.md b/README.md index e803a04..508f657 100644 --- a/README.md +++ b/README.md @@ -688,6 +688,10 @@ $browser->get($url)->then(function (Psr\Http\Message\ResponseInterface $response See also [example 01](examples/01-google.php). +> For BC reasons, this method accepts the `$url` as either a `string` + value or as an `UriInterface`. It's recommended to explicitly cast any + objects implementing `UriInterface` to `string`. + #### post() The `post(string|UriInterface $url, array $headers = array(), string|ReadableStreamInterface $contents = ''): PromiseInterface` method can be used to @@ -739,6 +743,10 @@ $loop->addTimer(1.0, function () use ($body) { $browser->post($url, array('Content-Length' => '11'), $body); ``` +> For BC reasons, this method accepts the `$url` as either a `string` + value or as an `UriInterface`. It's recommended to explicitly cast any + objects implementing `UriInterface` to `string`. + #### head() The `head(string|UriInterface $url, array $headers = array()): PromiseInterface` method can be used to @@ -750,6 +758,10 @@ $browser->head($url)->then(function (Psr\Http\Message\ResponseInterface $respons }); ``` +> For BC reasons, this method accepts the `$url` as either a `string` + value or as an `UriInterface`. It's recommended to explicitly cast any + objects implementing `UriInterface` to `string`. + #### patch() The `patch(string|UriInterface $url, array $headers = array(), string|ReadableStreamInterface $contents = ''): PromiseInterface` method can be used to @@ -782,6 +794,10 @@ $loop->addTimer(1.0, function () use ($body) { $browser->patch($url, array('Content-Length' => '11'), $body); ``` +> For BC reasons, this method accepts the `$url` as either a `string` + value or as an `UriInterface`. It's recommended to explicitly cast any + objects implementing `UriInterface` to `string`. + #### put() The `put(string|UriInterface $url, array $headers = array()): PromiseInterface` method can be used to @@ -816,6 +832,10 @@ $loop->addTimer(1.0, function () use ($body) { $browser->put($url, array('Content-Length' => '11'), $body); ``` +> For BC reasons, this method accepts the `$url` as either a `string` + value or as an `UriInterface`. It's recommended to explicitly cast any + objects implementing `UriInterface` to `string`. + #### delete() The `delete(string|UriInterface $url, array $headers = array()): PromiseInterface` method can be used to @@ -827,6 +847,10 @@ $browser->delete($url)->then(function (Psr\Http\Message\ResponseInterface $respo }); ``` +> For BC reasons, this method accepts the `$url` as either a `string` + value or as an `UriInterface`. It's recommended to explicitly cast any + objects implementing `UriInterface` to `string`. + #### request() The `request(string $method, string $url, array $headers = array(), string|ReadableStreamInterface $body = ''): PromiseInterface` method can be used to @@ -950,6 +974,10 @@ submit an array of field values similar to submitting a form (`application/x-www $browser->submit($url, array('user' => 'test', 'password' => 'secret')); ``` +> For BC reasons, this method accepts the `$url` as either a `string` + value or as an `UriInterface`. It's recommended to explicitly cast any + objects implementing `UriInterface` to `string`. + #### ~~send()~~ > Deprecated since v2.9.0, see [`request()`](#request) instead. @@ -1136,6 +1164,10 @@ This method will throw an `InvalidArgumentException` if the given Notice that the [`Browser`](#browser) is an immutable object, i.e. the `withBase()` method actually returns a *new* [`Browser`](#browser) instance with the given base URL applied. +> For BC reasons, this method accepts the `$baseUrl` as either a `string` + value or as an `UriInterface`. It's recommended to explicitly cast any + objects implementing `UriInterface` to `string`. + > Changelog: As of v2.9.0 this method accepts a `null` value to reset the base URL. Earlier versions had to use the deprecated `withoutBase()` method to reset the base URL. @@ -1240,6 +1272,10 @@ This is a standard interface defined in [PSR-7: HTTP message interfaces](https://www.php-fig.org/psr/psr-7/), see its [`UriInterface` definition](https://www.php-fig.org/psr/psr-7/#3-5-psr-http-message-uriinterface). +> For BC reasons, the request methods accept the URL as either a `string` + value or as an `UriInterface`. It's recommended to explicitly cast any + objects implementing `UriInterface` to `string`. + ### ResponseException The `ResponseException` is an `Exception` sub-class that will be used to reject diff --git a/src/Browser.php b/src/Browser.php index 2a8512a..e42409f 100644 --- a/src/Browser.php +++ b/src/Browser.php @@ -75,6 +75,10 @@ public function __construct(LoopInterface $loop, ConnectorInterface $connector = * * See also [example 01](../examples/01-google.php). * + * > For BC reasons, this method accepts the `$url` as either a `string` + * value or as an `UriInterface`. It's recommended to explicitly cast any + * objects implementing `UriInterface` to `string`. + * * @param string|UriInterface $url URL for the request. * @param array $headers * @return PromiseInterface @@ -133,6 +137,10 @@ public function get($url, array $headers = array()) * $browser->post($url, array('Content-Length' => '11'), $body); * ``` * + * > For BC reasons, this method accepts the `$url` as either a `string` + * value or as an `UriInterface`. It's recommended to explicitly cast any + * objects implementing `UriInterface` to `string`. + * * @param string|UriInterface $url URL for the request. * @param array $headers * @param string|ReadableStreamInterface $contents @@ -152,6 +160,10 @@ public function post($url, array $headers = array(), $contents = '') * }); * ``` * + * > For BC reasons, this method accepts the `$url` as either a `string` + * value or as an `UriInterface`. It's recommended to explicitly cast any + * objects implementing `UriInterface` to `string`. + * * @param string|UriInterface $url URL for the request. * @param array $headers * @return PromiseInterface @@ -191,6 +203,10 @@ public function head($url, array $headers = array()) * $browser->patch($url, array('Content-Length' => '11'), $body); * ``` * + * > For BC reasons, this method accepts the `$url` as either a `string` + * value or as an `UriInterface`. It's recommended to explicitly cast any + * objects implementing `UriInterface` to `string`. + * * @param string|UriInterface $url URL for the request. * @param array $headers * @param string|ReadableStreamInterface $contents @@ -233,6 +249,10 @@ public function patch($url, array $headers = array(), $contents = '') * $browser->put($url, array('Content-Length' => '11'), $body); * ``` * + * > For BC reasons, this method accepts the `$url` as either a `string` + * value or as an `UriInterface`. It's recommended to explicitly cast any + * objects implementing `UriInterface` to `string`. + * * @param string|UriInterface $url URL for the request. * @param array $headers * @param string|ReadableStreamInterface $contents @@ -252,6 +272,10 @@ public function put($url, array $headers = array(), $contents = '') * }); * ``` * + * > For BC reasons, this method accepts the `$url` as either a `string` + * value or as an `UriInterface`. It's recommended to explicitly cast any + * objects implementing `UriInterface` to `string`. + * * @param string|UriInterface $url URL for the request. * @param array $headers * @param string|ReadableStreamInterface $contents @@ -404,6 +428,10 @@ public function requestStreaming($method, $url, $headers = array(), $contents = * This method will automatically add a matching `Content-Length` request * header for the encoded length of the given `$fields`. * + * > For BC reasons, this method accepts the `$url` as either a `string` + * value or as an `UriInterface`. It's recommended to explicitly cast any + * objects implementing `UriInterface` to `string`. + * * @param string|UriInterface $url URL for the request. * @param array $fields * @param array $headers @@ -648,6 +676,10 @@ public function withRejectErrorResponse($obeySuccessCode) * Notice that the [`Browser`](#browser) is an immutable object, i.e. the `withBase()` method * actually returns a *new* [`Browser`](#browser) instance with the given base URL applied. * + * > For BC reasons, this method accepts the `$baseUrl` as either a `string` + * value or as an `UriInterface`. It's recommended to explicitly cast any + * objects implementing `UriInterface` to `string`. + * * > Changelog: As of v2.9.0 this method accepts a `null` value to reset the * base URL. Earlier versions had to use the deprecated `withoutBase()` * method to reset the base URL.