Merge pull request #2384 from Nyholm/frontendcoffee-2164

Update PHPDoc
guzzle · Oct 24, 2019 · 0cf5794 · 0cf5794
2 parents 7e387c1 + 7492367
commit 0cf5794
Show file tree

Hide file tree

Showing 8 changed files with 123 additions and 3 deletions.
diff --git 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
@@ -75,6 +75,12 @@ public function __construct(array $config = [])
         $this->configureDefaults($config);
     }
 
+    /**
+     * @param string $method
+     * @param array  $args
+     *
+     * @return Promise\PromiseInterface
+     */
     public function __call($method, $args)
     {
         if (count($args) < 1) {
@@ -89,6 +95,14 @@ public function __call($method, $args)
             : $this->request($method, $uri, $opts);
     }
 
+    /**
+     * Asynchronously send an HTTP request.
+     *
+     * @param array $options Request options to apply to the given
+     *                       request and to the transfer. See \GuzzleHttp\RequestOptions.
+     *
+     * @return PromiseInterface
+     */
     public function sendAsync(RequestInterface $request, array $options = [])
     {
         // Merge the base URI into the request URI if needed.
@@ -100,12 +114,35 @@ 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.
+     *
+     * @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. See \GuzzleHttp\RequestOptions.
+     *
+     * @return PromiseInterface
+     */
     public function requestAsync($method, $uri = '', array $options = [])
     {
         $options = $this->prepareDefaults($options);
@@ -125,19 +162,49 @@ 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. See \GuzzleHttp\RequestOptions.
+     *
+     * @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
             ? $this->config
             : (isset($this->config[$option]) ? $this->config[$option] : null);
     }
 
+    /**
+     * @param  string|null $uri
+     *
+     * @return UriInterface
+     */
     private function buildUri($uri, array $config)
     {
         // for BC we accept null which would otherwise fail in uri_for
@@ -154,6 +221,7 @@ private function buildUri($uri, array $config)
      * Configures the default options for a client.
      *
      * @param array $config
+     * @return void
      */
     private function configureDefaults(array $config)
     {
@@ -251,8 +319,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
      */
@@ -412,6 +479,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
@@ -168,6 +168,11 @@ function (array $matches) use ($request, $response, $error, &$cache) {
         );
     }
 
+    /**
+     * Get headers from message as string
+     *
+     * @return string
+     */
     private function headers(MessageInterface $message)
     {
         $result = '';

diff --git 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,11 @@ public static function batch(
         return $res;
     }
 
+    /**
+     * Execute callback(s)
+     *
+     * @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
@@ -66,6 +66,11 @@ public function __invoke(RequestInterface $request, array $options)
         return $fn(Psr7\modify_request($request, $modify), $options);
     }
 
+    /**
+     * Add expect header
+     *
+     * @return void
+     */
     private function addExpectHeader(
         RequestInterface $request,
         array $options,

diff --git a/src/RedirectMiddleware.php b/src/RedirectMiddleware.php
@@ -118,6 +118,11 @@ public function checkRedirect(
         return $promise;
     }
 
+    /**
+     * Enable tracking on promise.
+     *
+     * @return PromiseInterface
+     */
     private function withTracking(PromiseInterface $promise, $uri, $statusCode)
     {
         return $promise->then(
@@ -135,6 +140,13 @@ function (ResponseInterface $response) use ($uri, $statusCode) {
         );
     }
 
+    /**
+     * Check for too many redirects
+     *
+     * @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
@@ -74,6 +74,11 @@ public function __invoke(RequestInterface $request, array $options)
             );
     }
 
+    /**
+     * Execute fulfilled closure
+     *
+     * @return mixed
+     */
     private function onFulfilled(RequestInterface $req, array $options)
     {
         return function ($value) use ($req, $options) {
@@ -90,6 +95,11 @@ private function onFulfilled(RequestInterface $req, array $options)
         };
     }
 
+    /**
+     * Execute rejected closure
+     *
+     * @return callable
+     */
     private function onRejected(RequestInterface $req, array $options)
     {
         return function ($reason) use ($req, $options) {
@@ -106,6 +116,9 @@ private function onRejected(RequestInterface $req, array $options)
         };
     }
 
+    /**
+     * @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
@@ -56,7 +56,7 @@ 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
  */