Docs about batchSend() added

Author: klimov-paul

Client.php

@@ -215,6 +215,20 @@ public function send($request)
 
     /**
      * Performs multiple HTTP requests in parallel.
+     * This method accepts an array of the [[Request]] objects and returns an array of the  [[Response]] objects.
+     * Keys of the response array correspond the ones from request array.
+     *
+     * ```php
+     * $client = new Client();
+     * $requests = [
+     *     'news' => $client->get('http://domain.com/news'),
+     *     'friends' => $client->get('http://domain.com/user/friends', ['userId' => 12]),
+     * ];
+     * $responses = $client->batchSend($requests);
+     * var_dump($responses['news']->isOk);
+     * var_dump($responses['friends']->isOk);
+     * ```
+     *
      * @param Request[] $requests requests to perform.
      * @return Response[] responses list.
      */

Transport.php

@@ -29,6 +29,8 @@ abstract public function send($request);
     /**
      * Performs multiple HTTP requests.
      * Particular transport may benefit from this method, allowing sending requests in parallel.
+     * This method accepts an array of the [[Request]] objects and returns an array of the  [[Response]] objects.
+     * Keys of the response array correspond the ones from request array.
      * @param Request[] $requests requests to perform.
      * @return Response[] responses list.
      */

docs/guide/README.md

@@ -17,6 +17,7 @@ Usage
 * [Transports](usage-transports.md)
 * [Request options](usage-request-options.md)
 * [Multi-part content](usage-multi-part-content.md)
+* [Batch request sending](usage-batch-request-sending.md)
 * [Logging and profiling](usage-logging.md)
 * [Setup Client instance](usage-setup-client-instance.md)
 

docs/guide/usage-batch-request-sending.md

@@ -0,0 +1,55 @@
+Batch request sending
+=====================
+
+HTTP Client allows sending multiple requests at once using [[\yii\httpclient\Client::batchSend()]] method:
+
+```php
+use yii\httpclient\Client;
+
+$client = new Client();
+
+$requests = [
+    $client->get('http://domain.com/keep-alive'),
+    $client->post('http://domain.com/notify', ['userId' => 12]),
+];
+$responses = $client->batchSend($requests);
+```
+
+Particular [transport](usage-transports.md) may benefit from this method usage, allowing to increase the performance.
+Among the built-in transports, only [[\yii\httpclient\CurlTransport]] does this. It allows to send requests in parallel,
+which saves the program execution time.
+
+> Note: only some particular transports allows processing requests at `batchSend()` in special way, which provides some
+  benefit. By default transport just sends them one by one without any error or warning thrown. Make sure you have
+  configured correct transport for the client, if you wish to achieve performance boost.
+
+`batchSend()` method returns the array of the responses, which keys correspond the ones from array of requests.
+This allows you to process particular request response in easy way:
+
+```php
+use yii\httpclient\Client;
+
+$client = new Client();
+
+$requests = [
+    'news' => $client->get('http://domain.com/news'),
+    'friends' => $client->get('http://domain.com/user/friends', ['userId' => 12]),
+    'newComment' => $client->post('http://domain.com/user/comments', ['userId' => 12, 'content' => 'New comment']),
+];
+$responses = $client->batchSend($requests);
+
+// result of `GET http://domain.com/news` :
+if ($responses['news']->isOk) {
+    echo $responses['news']->content;
+}
+
+// result of `GET http://domain.com/user/friends` :
+if ($responses['friends']->isOk) {
+    echo $responses['friends']->content;
+}
+
+// result of `POST http://domain.com/user/comments` :
+if ($responses['newComment']->isOk) {
+    echo "Comment has been added successfully";
+}
+```