From 31a8b427ea9b5ba7bdffa37bed72c94a38673435 Mon Sep 17 00:00:00 2001 From: Jesse Kramer Date: Sat, 6 Oct 2018 23:01:51 +0200 Subject: [PATCH 1/5] Update PHPDoc --- src/Client.php | 78 ++++++++++++++++++++++++++++++++++- src/MessageFormatter.php | 5 +++ src/Pool.php | 11 +++++ src/PrepareBodyMiddleware.php | 7 ++++ src/RedirectMiddleware.php | 14 +++++++ src/RetryMiddleware.php | 19 +++++++++ src/functions.php | 2 +- 7 files changed, 134 insertions(+), 2 deletions(-) diff --git a/src/Client.php b/src/Client.php index aa5a89cd4..8ba0d0e80 100644 --- a/src/Client.php +++ b/src/Client.php @@ -75,7 +75,13 @@ public function __construct(array $config = []) $this->configureDefaults($config); } - public function __call($method, $args) + /** + * PHP Magic method + * @param string $method + * @param array $args + * @return Promise\PromiseInterface + */ + public function __call($method, array $args) { if (count($args) < 1) { throw new \InvalidArgumentException('Magic request methods require a URI and optional options array'); @@ -89,6 +95,15 @@ public function __call($method, $args) : $this->request($method, $uri, $opts); } + /** + * Asynchronously send an HTTP request. + * + * @param RequestInterface $request Request to send + * @param array $options Request options to apply to the given + * request and to the transfer. + * + * @return PromiseInterface + */ public function sendAsync(RequestInterface $request, array $options = []) { // Merge the base URI into the request URI if needed. @@ -100,12 +115,36 @@ public function sendAsync(RequestInterface $request, array $options = []) ); } + /** + * Send an HTTP request. + * + * @param RequestInterface $request Request to send + * @param array $options Request options to apply to the given + * request and to the transfer. + * + * @return ResponseInterface + * @throws GuzzleException + */ public function send(RequestInterface $request, array $options = []) { $options[RequestOptions::SYNCHRONOUS] = true; return $this->sendAsync($request, $options)->wait(); } + /** + * Create and send an asynchronous HTTP request. + * + * Use an absolute path to override the base path of the client, or a + * relative path to append to the base path of the client. The URL can + * contain the query string as well. Use an array to provide a URL + * template and additional variables to use in the URL template expansion. + * + * @param string $method HTTP method + * @param string|UriInterface $uri URI object or string. + * @param array $options Request options to apply. + * + * @return PromiseInterface + */ public function requestAsync($method, $uri = '', array $options = []) { $options = $this->prepareDefaults($options); @@ -125,12 +164,37 @@ public function requestAsync($method, $uri = '', array $options = []) return $this->transfer($request, $options); } + /** + * Create and send an HTTP request. + * + * Use an absolute path to override the base path of the client, or a + * relative path to append to the base path of the client. The URL can + * contain the query string as well. + * + * @param string $method HTTP method. + * @param string|UriInterface $uri URI object or string. + * @param array $options Request options to apply. + * + * @return ResponseInterface + * @throws GuzzleException + */ public function request($method, $uri = '', array $options = []) { $options[RequestOptions::SYNCHRONOUS] = true; return $this->requestAsync($method, $uri, $options)->wait(); } + /** + * Get a client configuration option. + * + * These options include default request options of the client, a "handler" + * (if utilized by the concrete client), and a "base_uri" if utilized by + * the concrete client. + * + * @param string|null $option The config option to retrieve. + * + * @return mixed + */ public function getConfig($option = null) { return $option === null @@ -138,6 +202,12 @@ public function getConfig($option = null) : (isset($this->config[$option]) ? $this->config[$option] : null); } + /** + * Build URI object. + * @param string|null $uri + * @param array $config + * @return UriInterface + */ private function buildUri($uri, array $config) { // for BC we accept null which would otherwise fail in uri_for @@ -154,6 +224,7 @@ private function buildUri($uri, array $config) * Configures the default options for a client. * * @param array $config + * @return void */ private function configureDefaults(array $config) { @@ -412,6 +483,11 @@ private function applyOptions(RequestInterface $request, array &$options) return $request; } + /** + * Throw Exception with pre-set message. + * @return void + * @throws InvalidArgumentException Invalid body. + */ private function invalidBody() { throw new \InvalidArgumentException('Passing in the "body" request ' diff --git a/src/MessageFormatter.php b/src/MessageFormatter.php index 663ac7391..8401f9936 100644 --- a/src/MessageFormatter.php +++ b/src/MessageFormatter.php @@ -168,6 +168,11 @@ function (array $matches) use ($request, $response, $error, &$cache) { ); } + /** + * Get headers from message as string + * @param MessageInterface $message + * @return string + */ private function headers(MessageInterface $message) { $result = ''; diff --git a/src/Pool.php b/src/Pool.php index 05c854aeb..8c129f933 100644 --- a/src/Pool.php +++ b/src/Pool.php @@ -69,6 +69,10 @@ public function __construct( $this->each = new EachPromise($requests(), $config); } + /** + * Get promise + * @return GuzzleHttp\Promise\Promise + */ public function promise() { return $this->each->promise(); @@ -106,6 +110,13 @@ public static function batch( return $res; } + /** + * Execute callback(s) + * @param array $options + * @param string $name + * @param array $results + * @return void + */ private static function cmpCallback(array &$options, $name, array &$results) { if (!isset($options[$name])) { diff --git a/src/PrepareBodyMiddleware.php b/src/PrepareBodyMiddleware.php index 2eb95f9b2..3214b5477 100644 --- a/src/PrepareBodyMiddleware.php +++ b/src/PrepareBodyMiddleware.php @@ -66,6 +66,13 @@ public function __invoke(RequestInterface $request, array $options) return $fn(Psr7\modify_request($request, $modify), $options); } + /** + * Add expect header + * @param RequestInterface $request + * @param array $options + * @param array $modify + * @return void + */ private function addExpectHeader( RequestInterface $request, array $options, diff --git a/src/RedirectMiddleware.php b/src/RedirectMiddleware.php index 84f6785e6..7de9574c3 100644 --- a/src/RedirectMiddleware.php +++ b/src/RedirectMiddleware.php @@ -118,6 +118,13 @@ public function checkRedirect( return $promise; } + /** + * Enable tracking on promise. + * @param PromiseInterface $promise + * @param string $uri + * @param string $statusCode [description] + * @return PromiseInterface + */ private function withTracking(PromiseInterface $promise, $uri, $statusCode) { return $promise->then( @@ -135,6 +142,13 @@ function (ResponseInterface $response) use ($uri, $statusCode) { ); } + /** + * Check for too many redirects + * @param RequestInterface $request + * @param array $options + * @return void + * @throws TooManyRedirectsException Too many redirects. + */ private function guardMax(RequestInterface $request, array &$options) { $current = isset($options['__redirect_count']) diff --git a/src/RetryMiddleware.php b/src/RetryMiddleware.php index 7d40ecaf8..355cd1057 100644 --- a/src/RetryMiddleware.php +++ b/src/RetryMiddleware.php @@ -74,6 +74,12 @@ public function __invoke(RequestInterface $request, array $options) ); } + /** + * Execute fulfilled closure + * @param RequestInterface $req + * @param array $options + * @return mixed + */ private function onFulfilled(RequestInterface $req, array $options) { return function ($value) use ($req, $options) { @@ -90,6 +96,12 @@ private function onFulfilled(RequestInterface $req, array $options) }; } + /** + * Execute rejected closure + * @param RequestInterface $req + * @param array $options + * @return mixed + */ private function onRejected(RequestInterface $req, array $options) { return function ($reason) use ($req, $options) { @@ -106,6 +118,13 @@ private function onRejected(RequestInterface $req, array $options) }; } + /** + * Retry + * @param RequestInterface $req + * @param array $options + * @param ResponseInterface $response + * @return self + */ private function doRetry(RequestInterface $request, array $options, ResponseInterface $response = null) { $options['delay'] = call_user_func($this->delay, ++$options['retries'], $response); diff --git a/src/functions.php b/src/functions.php index 51d736d88..96dcef942 100644 --- a/src/functions.php +++ b/src/functions.php @@ -60,7 +60,7 @@ function describe_type($input) * format: "Name: Value" * @return array */ -function headers_from_lines($lines) +function headers_from_lines(array $lines) { $headers = []; From f9c53e0f998ee845ee33e8de8a2f270bb3e9c8aa Mon Sep 17 00:00:00 2001 From: Jesse Kramer Date: Mon, 22 Oct 2018 13:22:46 +0200 Subject: [PATCH 2/5] Update BC breaking typehints. --- src/RetryMiddleware.php | 2 +- src/functions.php | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/src/RetryMiddleware.php b/src/RetryMiddleware.php index 355cd1057..d1bdf49c2 100644 --- a/src/RetryMiddleware.php +++ b/src/RetryMiddleware.php @@ -100,7 +100,7 @@ private function onFulfilled(RequestInterface $req, array $options) * Execute rejected closure * @param RequestInterface $req * @param array $options - * @return mixed + * @return callable */ private function onRejected(RequestInterface $req, array $options) { diff --git a/src/functions.php b/src/functions.php index 96dcef942..aff69d557 100644 --- a/src/functions.php +++ b/src/functions.php @@ -56,11 +56,11 @@ function describe_type($input) /** * Parses an array of header lines into an associative array of headers. * - * @param array $lines Header lines array of strings in the following + * @param iterable $lines Header lines array of strings in the following * format: "Name: Value" * @return array */ -function headers_from_lines(array $lines) +function headers_from_lines($lines) { $headers = []; From fb6b954530552741125cb007a24f00b0841bb938 Mon Sep 17 00:00:00 2001 From: Nyholm Date: Wed, 23 Oct 2019 22:04:32 +0200 Subject: [PATCH 3/5] Removed comments not needed --- src/Client.php | 19 +++++++------------ src/MessageFormatter.php | 2 +- src/Pool.php | 4 +--- src/PrepareBodyMiddleware.php | 4 +--- src/RedirectMiddleware.php | 8 +++----- src/RetryMiddleware.php | 10 ++-------- 6 files changed, 15 insertions(+), 32 deletions(-) diff --git a/src/Client.php b/src/Client.php index 8ba0d0e80..3490d6a52 100644 --- a/src/Client.php +++ b/src/Client.php @@ -76,9 +76,8 @@ public function __construct(array $config = []) } /** - * PHP Magic method * @param string $method - * @param array $args + * * @return Promise\PromiseInterface */ public function __call($method, array $args) @@ -98,9 +97,8 @@ public function __call($method, array $args) /** * Asynchronously send an HTTP request. * - * @param RequestInterface $request Request to send * @param array $options Request options to apply to the given - * request and to the transfer. + * request and to the transfer. See \GuzzleHttp\RequestOptions. * * @return PromiseInterface */ @@ -118,9 +116,8 @@ public function sendAsync(RequestInterface $request, array $options = []) /** * Send an HTTP request. * - * @param RequestInterface $request Request to send * @param array $options Request options to apply to the given - * request and to the transfer. + * request and to the transfer. See \GuzzleHttp\RequestOptions. * * @return ResponseInterface * @throws GuzzleException @@ -141,7 +138,7 @@ public function send(RequestInterface $request, array $options = []) * * @param string $method HTTP method * @param string|UriInterface $uri URI object or string. - * @param array $options Request options to apply. + * @param array $options Request options to apply. See \GuzzleHttp\RequestOptions. * * @return PromiseInterface */ @@ -173,7 +170,7 @@ public function requestAsync($method, $uri = '', array $options = []) * * @param string $method HTTP method. * @param string|UriInterface $uri URI object or string. - * @param array $options Request options to apply. + * @param array $options Request options to apply. See \GuzzleHttp\RequestOptions. * * @return ResponseInterface * @throws GuzzleException @@ -203,9 +200,8 @@ public function getConfig($option = null) } /** - * Build URI object. * @param string|null $uri - * @param array $config + * * @return UriInterface */ private function buildUri($uri, array $config) @@ -322,8 +318,7 @@ private function prepareDefaults(array $options) * The URI of the request is not modified and the request options are used * as-is without merging in default options. * - * @param RequestInterface $request - * @param array $options + * @param array $options See \GuzzleHttp\RequestOptions. * * @return Promise\PromiseInterface */ diff --git a/src/MessageFormatter.php b/src/MessageFormatter.php index 8401f9936..dc36bb524 100644 --- a/src/MessageFormatter.php +++ b/src/MessageFormatter.php @@ -170,7 +170,7 @@ function (array $matches) use ($request, $response, $error, &$cache) { /** * Get headers from message as string - * @param MessageInterface $message + * * @return string */ private function headers(MessageInterface $message) diff --git a/src/Pool.php b/src/Pool.php index 8c129f933..2ff6796c7 100644 --- a/src/Pool.php +++ b/src/Pool.php @@ -112,9 +112,7 @@ public static function batch( /** * Execute callback(s) - * @param array $options - * @param string $name - * @param array $results + * * @return void */ private static function cmpCallback(array &$options, $name, array &$results) diff --git a/src/PrepareBodyMiddleware.php b/src/PrepareBodyMiddleware.php index 3214b5477..568a1e906 100644 --- a/src/PrepareBodyMiddleware.php +++ b/src/PrepareBodyMiddleware.php @@ -68,9 +68,7 @@ public function __invoke(RequestInterface $request, array $options) /** * Add expect header - * @param RequestInterface $request - * @param array $options - * @param array $modify + * * @return void */ private function addExpectHeader( diff --git a/src/RedirectMiddleware.php b/src/RedirectMiddleware.php index 7de9574c3..5a0edd572 100644 --- a/src/RedirectMiddleware.php +++ b/src/RedirectMiddleware.php @@ -120,9 +120,7 @@ public function checkRedirect( /** * Enable tracking on promise. - * @param PromiseInterface $promise - * @param string $uri - * @param string $statusCode [description] + * * @return PromiseInterface */ private function withTracking(PromiseInterface $promise, $uri, $statusCode) @@ -144,9 +142,9 @@ function (ResponseInterface $response) use ($uri, $statusCode) { /** * Check for too many redirects - * @param RequestInterface $request - * @param array $options + * * @return void + * * @throws TooManyRedirectsException Too many redirects. */ private function guardMax(RequestInterface $request, array &$options) diff --git a/src/RetryMiddleware.php b/src/RetryMiddleware.php index d1bdf49c2..c8d72c200 100644 --- a/src/RetryMiddleware.php +++ b/src/RetryMiddleware.php @@ -76,8 +76,7 @@ public function __invoke(RequestInterface $request, array $options) /** * Execute fulfilled closure - * @param RequestInterface $req - * @param array $options + * * @return mixed */ private function onFulfilled(RequestInterface $req, array $options) @@ -98,8 +97,7 @@ private function onFulfilled(RequestInterface $req, array $options) /** * Execute rejected closure - * @param RequestInterface $req - * @param array $options + * * @return callable */ private function onRejected(RequestInterface $req, array $options) @@ -119,10 +117,6 @@ private function onRejected(RequestInterface $req, array $options) } /** - * Retry - * @param RequestInterface $req - * @param array $options - * @param ResponseInterface $response * @return self */ private function doRetry(RequestInterface $request, array $options, ResponseInterface $response = null) From 2a9a0f007de33cf4251ec3f02683aaae921aea8c Mon Sep 17 00:00:00 2001 From: Nyholm Date: Wed, 23 Oct 2019 22:14:15 +0200 Subject: [PATCH 4/5] PHPStan config --- phpstan.neon.dist | 4 ++++ src/Client.php | 12 ++++++------ 2 files changed, 10 insertions(+), 6 deletions(-) diff --git a/phpstan.neon.dist b/phpstan.neon.dist index 4ef4192d3..70d5cb32f 100644 --- a/phpstan.neon.dist +++ b/phpstan.neon.dist @@ -7,3 +7,7 @@ parameters: - message: '#Function uri_template not found#' path: %currentWorkingDirectory%/src/functions.php + + + # To be removed when we drop support for PHP5 + - '#Return typehint of method#' diff --git a/src/Client.php b/src/Client.php index 3490d6a52..5048bb406 100644 --- a/src/Client.php +++ b/src/Client.php @@ -76,7 +76,7 @@ public function __construct(array $config = []) } /** - * @param string $method + * @param string $method * * @return Promise\PromiseInterface */ @@ -97,8 +97,8 @@ public function __call($method, array $args) /** * Asynchronously send an HTTP request. * - * @param array $options Request options to apply to the given - * request and to the transfer. See \GuzzleHttp\RequestOptions. + * @param array $options Request options to apply to the given + * request and to the transfer. See \GuzzleHttp\RequestOptions. * * @return PromiseInterface */ @@ -116,8 +116,8 @@ public function sendAsync(RequestInterface $request, array $options = []) /** * Send an HTTP request. * - * @param array $options Request options to apply to the given - * request and to the transfer. See \GuzzleHttp\RequestOptions. + * @param array $options Request options to apply to the given + * request and to the transfer. See \GuzzleHttp\RequestOptions. * * @return ResponseInterface * @throws GuzzleException @@ -318,7 +318,7 @@ private function prepareDefaults(array $options) * The URI of the request is not modified and the request options are used * as-is without merging in default options. * - * @param array $options See \GuzzleHttp\RequestOptions. + * @param array $options See \GuzzleHttp\RequestOptions. * * @return Promise\PromiseInterface */ From 74923670dd2ceb476215dd2b8aec7242d8ecbc67 Mon Sep 17 00:00:00 2001 From: Nyholm Date: Wed, 23 Oct 2019 22:27:38 +0200 Subject: [PATCH 5/5] Reverted BC break --- src/Client.php | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/Client.php b/src/Client.php index 5048bb406..7f80efcf0 100644 --- a/src/Client.php +++ b/src/Client.php @@ -77,10 +77,11 @@ public function __construct(array $config = []) /** * @param string $method + * @param array $args * * @return Promise\PromiseInterface */ - public function __call($method, array $args) + public function __call($method, $args) { if (count($args) < 1) { throw new \InvalidArgumentException('Magic request methods require a URI and optional options array');