Docs updated

Author: klimov-paul

README.md

@@ -28,9 +28,3 @@ or add
 ```
 
 to the require section of your composer.json.
-
-
-Configuration
--------------
-
-To use this extension, simply

docs/guide/README.md

@@ -8,4 +8,17 @@ Getting Started
 ---------------
 
 * [Installation](installation.md)
-* [Quick Start](quick-start.md)
+* [Basic Usage](basic-usage.md)
+
+Usage
+-----
+
+* [Data formats](usage-data-formats.md)
+* [Transports](usage-transports.md)
+* [Logging and profiling](usage-logging.md)
+* [Setup Client instance](usage-setup-client-instance.md)
+
+Additional topics
+-----------------
+
+* [Using the HTTP client DebugPanel](topics-debug.md)

docs/guide/quick-start.md renamed to docs/guide/basic-usage.md

@@ -1,8 +1,6 @@
-Quick Start
+Basic Usage
 ===========
 
-## Basic usage
-
 In order to send HTTP requests, you'll need to instantiate [[\yii\httpclient\Client]] and use its
 `createRequest()` method to create new HTTP request. Then you should configure all request parameters
 according to your goal and send request. As the result you'll get a [[\yii\httpclient\Response]] instance,

docs/guide/topics-debug.md

@@ -0,0 +1,31 @@
+Using the HTTP Client DebugPanel
+================================
+
+The yii2 HTTP Client  extension provides a debug panel that can be integrated with the yii debug module
+and shows the executed HTTP requests.
+
+Add the following to you application config to enable it (if you already have the debug module
+enabled, it is sufficient to just add the panels configuration):
+
+```php
+    // ...
+    'bootstrap' => ['debug'],
+    'modules' => [
+        'debug' => [
+            'class' => 'yii\\debug\\Module',
+            'panels' => [
+                'httpclient' => [
+                    'class' => 'yii\\httpclient\\debug\\HttpClientPanel',
+                ],
+            ],
+        ],
+    ],
+    // ...
+```
+
+This panel allows you execution of the logged HTTP request to see its response. You may get the response as
+a text representation or pass it directly to the browser.
+
+> Note: only regular logged HTTP requests can be executed via debug panel, requests sending in batch can not.
+  Also keep in mind that content of logged request can be trimmed according to [[\yii\httpclient\Client::contentLoggingMaxSize]],
+  so its execution may fail or produce unexpected results.

docs/guide/usage-data-formats.md

@@ -0,0 +1,64 @@
+Data Formats
+============
+
+Data format determines the way content of HTTP message should be composed or parsed, e.g. it determines
+how [[\yii\httpclient\Message::data]] should be converted into [[\yii\httpclient\Message::content]] and vice versa.
+
+Following formats are supported by default:
+
+ - [[\yii\httpclient\Client::FORMAT_JSON]] - JSON format
+ - [[\yii\httpclient\Client::FORMAT_URLENCODED]] - urlencoded by RFC1738 query string
+ - [[\yii\httpclient\Client::FORMAT_RAW_URLENCODED]] - urlencoded by PHP_QUERY_RFC3986 query string
+ - [[\yii\httpclient\Client::FORMAT_XML]] - XML format
+
+Each format is covered by 2 entities: 'formatter' and 'parser'. Formatter determines the way content of the
+request should be composed from data. Parser determines how raw response content should be parsed into data.
+
+[[\yii\httpclient\Client]] automatically chooses corresponding formatter and parser for all format mentioned above.
+However you can alter this behavior using [[\yii\httpclient\Client::formatters]] and [[\yii\httpclient\Client::parsers]].
+With these fields you can add you own formats or alter standard ones.
+For example:
+
+```php
+use yii\httpclient\Client;
+
+$client = new Client([
+    'formatters' => [
+        'myformat' => 'app\components\http\MyFormatter', // add new formatter
+        Client::FORMAT_XML => 'app\components\http\MyXMLFormatter', // override default XML formatter
+    ],
+]);
+```
+
+While creating your own parser you should implement [[\yii\httpclient\ParserInterface]], while creating
+formatter - [[\yii\httpclient\FormatterInterface]]. For example:
+
+```php
+use yii\httpclient\FormatterInterface;
+use yii\httpclient\ParserInterface;
+use yii\httpclient\Response;
+
+class ParserIni implements ParserInterface
+{
+    public function parse(Response $response)
+    {
+        return parse_ini_string($response->content);
+    }
+}
+
+class FormatterIni implements FormatterInterface
+{
+    public function format(Request $request)
+    {
+        $request->getHeaders()->set('Content-Type', 'text/ini   ; charset=UTF-8');
+
+        $pairs = []
+        foreach ($request->data as $name => $value) {
+            $pairs[] = "$name=$value";
+        }
+
+        $request->setContent(implode("\n", $pairs));
+        return $request;
+    }
+}
+```

docs/guide/usage-logging.md

@@ -0,0 +1,33 @@
+Logging and Profiling
+=====================
+
+This extension allows logging HTTP requests being sent and profiling their execution.
+In order to setup a log target, which can capture all entries related to HTTP requests, you should
+use category `yii\httpclient\Transport*`. For example:
+
+```php
+return [
+    // ...
+    'components' => [
+        // ...
+        'log' => [
+            // ...
+            'targets' => [
+                [
+                    'class' => 'yii\log\FileTarget',
+                    'logFile' => '@runtime/logs/http-request.log',
+                    'categories' => ['yii\httpclient\Transport*'],
+                ],
+                // ...
+            ],
+        ],
+    ],
+];
+```
+
+You may as well use [HTTP client DebugPanel](topics-debug.md) to see all related logs.
+
+> Attention: since content of the some HTTP requests may be very long, saving it in full inside the logs
+  may lead to certain problems. Thus there is a restriction on the maximum length of the request content,
+  which will be placed in log. It is controlled by [[\yii\httpclient\Client::contentLoggingMaxSize]].
+  Any exceeding content will be trimmed before logging.

docs/guide/usage-setup-client-instance.md

@@ -0,0 +1,93 @@
+Setup Client instance
+=====================
+
+Using of this extension starts from instantiating [[\yii\httpclient\Client]] object. There are several ways
+you can integrate [[\yii\httpclient\Client]] to your program. Here the most common approaches are described.
+
+
+## Setup client as application component
+
+[[\yii\httpclient\Client]] extends [[\yii\base\Component]] and thus it can be setup at [[\yii\di\Container]]
+level: as module or application component. For example:
+
+```php
+return [
+    // ...
+    'components' => [
+        // ...
+        'phpNetHttp' => [
+            'class' => 'yii\httpclient\Client',
+            'baseUrl' => 'http://uk.php.net',
+        ],
+    ],
+];
+
+// ...
+echo Yii::$app->phpNetHttp->get('docs.php')->send()->content;
+```
+
+
+## Extending client class
+
+Since [[\yii\httpclient\Client]] can be used as application component, you can just extend it, adding some
+custom logic, which you need. For example:
+
+```php
+use yii\httpclient\Client;
+
+class MyRestApi extends Client
+{
+    public $baseUrl = 'http://my.rest.api/';
+
+    public function addUser(array $data)
+    {
+        $response = $this->post('users', $data)->send();
+        if (!$response->isOk) {
+            throw new \Exception('Unable to add user.');
+        }
+        return $response->data['id'];
+    }
+
+    // ...
+}
+```
+
+
+## Wrapping client object
+
+You may use [[\yii\httpclient\Client]] instance as internal field for component, which provides some complex
+functionality. For example:
+
+```php
+use yii\base\Component;
+use yii\httpclient\Client;
+
+class MyRestApi extends Component
+{
+    public $baseUrl = 'http://my.rest.api/';
+
+    private $_httpClient;
+
+    public function getHttpClient()
+    {
+        if (!is_object($this->_httpClient)) {
+            $this->_httpClient = Yii::createObject([
+                'class' => Client::className(),
+                'baseUrl' => $this->baseUrl,
+            ]);
+        }
+        return $this->_httpClient;
+    }
+
+    public function addUser(array $data)
+    {
+        $response = $this->getHttpClient()->post('users', $data)->send();
+        if (!$response->isOk) {
+            throw new \Exception('Unable to add user.');
+        }
+        return $response->data['id'];
+    }
+
+    // ...
+}
+```

docs/guide/usage-transports.md

@@ -0,0 +1,51 @@
+Transports
+==========
+
+[[\yii\httpclient\Client]] provides several different ways to actually send an HTTP message - several transports.
+Predefined transports are:
+
+ - [[\yii\httpclient\TransportStream]] - sends HTTP messages using [Streams](http://php.net/manual/en/book.stream.php).
+   This transport is used by default. It does not require any additional PHP extensions or libraries installed,
+   but does not support advanced features like batch sending.
+ - [[\yii\httpclient\TransportCurl]] - sends HTTP messages using [Client URL Library (cURL)](http://php.net/manual/en/book.curl.php)
+   This transport requires PHP 'curl' extension to be installed, but provides support for advanced features, like
+   batch sending.
+
+You may configure the transport to be used by particular client using [[\yii\httpclient\Client::transport]]:
+
+```php
+use yii\httpclient\Client;
+
+$client = new Client([
+    'transport' => 'yii\httpclient\TransportCurl'
+]);
+```
+
+
+## Creating custom transport
+
+You may create your own transport, which will perform message sending in its own way. To do so you should
+extend [[\yii\httpclient\Transport]] class and implement at least `send()` method. All you need to do is
+determine HTTP response content and headers, then you can compose a response object from them using
+[[\yii\httpclient\Client::createResponse()]]:
+
+```php
+use yii\httpclient\Transport;
+
+class MyTransport extends Transport
+{
+    /**
+     * @inheritdoc
+     */
+    public function send($request)
+    {
+        $responseContent = '???';
+        $responseHeaders = ['???'];
+
+        return $request->client->createResponse($responseContent, $responseHeaders);
+    }
+}
+```
+
+You may as well override `batchSend()` method if there is a way to send multiple requests with better performance
+like sending them asynchronously in parallel.