Updated documentation for v2.0

README.md

@@ -13,10 +13,13 @@ CsaGuzzleBundle
 Description
 -----------
 
-This bundle integrates Guzzle >=4.0 in Symfony. Currently, it supports the following features:
+This bundle integrates Guzzle >=4.0 in Symfony. The `1.x` branch supports Guzzle 4 and 5, and the `master` branch supports Guzzle 6.
+
+Currently, it supports the following features:
 
 * Integration with Symfony's debug tools (web debug toolbar, profiler, logger, timeline, ...)
 * Configuring a Guzzle client simply using configuration
+* Multiple middleware / subscribers (logger, profiler, timeline, cache, mock, and more to come)
 * Service descriptions to describe your services is json format (only in the 1.3 branch, though)
 
 ![Web debug Toolbar](https://cloud.githubusercontent.com/assets/465798/7407652/dda8bda4-ef14-11e4-9e9e-1db2fa6a346d.png)
@@ -26,49 +29,7 @@ This bundle integrates Guzzle >=4.0 in Symfony. Currently, it supports the follo
 Installation
 ------------
 
-### Stable version
-
-Add the required package using composer.
-
-```bash
-composer require csa/guzzle-bundle:@stable
-```
-
-### Bleeding-edge version
-
-Add the required package using composer.
-
-```bash
-composer require csa/guzzle-bundle:@dev
-```
-
-### Enabling the bundle
-
-Add the bundle to your AppKernel.
-
-```php
-// in %kernel.root_dir%/AppKernel.php
-$bundles = array(
-    // ...
-    new Csa\Bundle\GuzzleBundle\CsaGuzzleBundle(),
-    // ...
-);
-```
-
-To enable the data collector (only in the `dev` environment, you may simply
-configure the CsaGuzzleBundle as follows:
-
-```yml
-csa_guzzle:
-    profiler: %kernel.debug%
-```
-
-You may also enable the included logger, in order log outcoming requests:
-
-```yml
-csa_guzzle:
-    logger: true
-```
+All the installation instructions are located in the documentation
 
 Upgrade
 -------
@@ -83,21 +44,21 @@ Documentation
 
 ### Documentation for stable (2.0@dev/dev-master)
 
+* [Installation](src/Resources/doc/install.md)
 * [Creating clients](src/Resources/doc/clients.md)
 * [Registering new middleware](src/Resources/doc/middleware.md)
 * [Available middleware](src/Resources/doc/available_middleware.md)
-* [Configuration reference](src/Resources/doc/configuration_reference.md)
 * [Streaming a guzzle response](src/Resources/doc/response_streaming.md)
-* [Mock HTTP requests in tests](src/Resources/doc/tests_mock_http_requests.md)
+* [Configuration reference](src/Resources/doc/configuration_reference.md)
 
 ### Documentation for legacy (1.3)
 
 * [Creating clients](../1.3/src/Resources/doc/clients.md)
 * [Registering new event subscribers](../1.3/src/Resources/doc/event_subscribers.md)
 * [Available event subscribers](../1.3/src/Resources/doc/available_subscribers.md)
-* [Configuration reference](../1.3/src/Resources/doc/configuration_reference.md)
 * [Streaming a guzzle response](../1.3/src/Resources/doc/response_streaming.md)
 * [Service descriptions](../1.3/src/Resources/doc/service_descriptions.md)
+* [Configuration reference](../1.3/src/Resources/doc/configuration_reference.md)
 
 Contributing
 ------------

src/Resources/doc/available_middleware.md

@@ -7,6 +7,7 @@ Currently, four middleware are available:
 * the `stopwatch` middleware
 * the `logger` middleware
 * the `cache` middleware
+* the `mock` middleware
 
 
 The `debug` and `stopwatch` middleware
@@ -107,3 +108,39 @@ class, in which you should inject your doctrine cache service. For example, usin
     <argument>%kernel.cache_dir%/my_cache_folder</argument>
 </service>
 ```
+
+The `mock` middleware
+---------------------
+
+When running tests, you often want to disable real HTTP requests to your (or an external) API.
+The `mock` middleware can record those requests to replay them in tests.
+
+The `mock` middleware can work in two modes:
+
+* record, which saves your HTTP requests inside a directory in your filesystem
+* replay, which uses your saved HTTP requests from the same directory
+
+Of course, this middleware should only be used in the `test` environment (or `dev`, if you don't have
+access to the remote server):
+
+```yml
+# config_test.yml
+csa_guzzle:
+    mock:
+        storage_path: "%kernel.root_dir%/../features/fixtures/guzzle"
+        mode: record
+```
+
+The generated files can then be committed in the VCS.
+
+To use them, simply change the mode to `replay`:
+
+```yml
+# config_test.yml
+csa_guzzle:
+    mock:
+        storage_path: "%kernel.root_dir%/../features/fixtures/guzzle"
+        mode: replay
+```
+
+Next Section: [Streaming a guzzle response](response_streaming.md)

src/Resources/doc/clients.md

@@ -16,10 +16,9 @@ csa_guzzle:
     clients:
         github_api:
             config:
-                base_url: https://api.github.com
-                defaults:
-                    headers:
-                        Accept: application/vnd.github.v3+json
+                base_uri: https://api.github.com
+                headers:
+                    Accept: application/vnd.github.v3+json
 ```
 
 The previous code will create a new service, called `csa_guzzle.client.github_api`, that you can use in your controller, or that you can inject in another service:
@@ -63,3 +62,5 @@ To have a client supported by the bundle, simply tag it as such:
     <tag name="csa_guzzle.client" />
 </service>
 ```
+
+Next section: [Registering new middleware](middleware.md)

src/Resources/doc/configuration_reference.md

@@ -11,15 +11,23 @@ csa_guzzle:
     logger:
         enabled:              false
         service:              ~
-        format:               clf
+        format:               '{hostname} {req_header_User-Agent} - [{date_common_log}] "{method} {target} HTTP/{version}" {code} {res_header_Content-Length}'
+        level:                debug
     cache:
-        enabled: false
-        adapter: ~
+        enabled:              false
+        adapter:              ~
     clients:
 
         # Prototype
         name:
+            class:            GuzzleHttp\Client
             config:           ~
             middleware:       []
-            class:            GuzzleHttp\Client
+            alias:            ~
+    mock:
+        enabled:              false
+        storage_path:         ~ # Required
+        mode:                 replay
 ```
+
+[Back to index](../../../README.md)

src/Resources/doc/install.md

@@ -0,0 +1,58 @@
+Installation and Configuration
+==============================
+
+Installation
+------------
+
+Add the required package using composer.
+
+### Stable version
+
+```bash
+composer require csa/guzzle-bundle:^2.0
+```
+
+### Legacy version
+
+```bash
+composer require csa/guzzle-bundle:^1.3
+```
+
+### Bleeding-edge version
+
+```bash
+composer require csa/guzzle-bundle:@dev
+```
+
+### Enabling the bundle
+
+Add the bundle to your AppKernel.
+
+```php
+// in %kernel.root_dir%/AppKernel.php
+$bundles = array(
+    // ...
+    new Csa\Bundle\GuzzleBundle\CsaGuzzleBundle(),
+    // ...
+);
+```
+
+Configuration
+-------------
+
+To enable the data collector (only in the `dev` environment, you may simply
+configure the CsaGuzzleBundle as follows:
+
+```yml
+csa_guzzle:
+    profiler: %kernel.debug%
+```
+
+You may also enable the included logger, in order log outcoming requests:
+
+```yml
+csa_guzzle:
+    logger: true
+```
+
+Next section: [Creating clients](clients.md)

src/Resources/doc/middleware.md

@@ -2,14 +2,15 @@ Creating new middleware
 =======================
 
 Creating a new Guzzle [middleware](http://guzzle.readthedocs.org/en/latest/handlers-and-middleware.html#middleware)
-is as easy as creating a symfony service and using the `csa_guzzle.middleware` tag, giving it an alias:
+is as easy as creating a symfony service and using the `csa_guzzle.middleware` tag, giving it an alias and
+(optionally) a priority:
 
 ```xml
 <service
         id="acme.middleware"
         class="Closure">
     <factory class="My\Middleware" method="my_middleware" />
-    <tag name="csa_guzzle.middleware" alias="my_middleware" />
+    <tag name="csa_guzzle.middleware" alias="my_middleware" priority="100" />
 </service>
 ```
 
@@ -24,10 +25,9 @@ csa_guzzle:
         # Prototype
         github_api:
             config:
-                base_url: https://api.github.com
-                defaults:
-                    headers:
-                        Accept: application/vnd.github.v3+json
+                base_uri: https://api.github.com
+                headers:
+                    Accept: application/vnd.github.v3+json
             middleware: [debug, my_middleware] # Note the use of the alias defined earlier in the service definition.
 ```
 
@@ -41,3 +41,5 @@ for that client:
     <tag name="csa_guzzle.client" middleware="my_middleware another_middleware" />
 </service>
 ```
+
+Next section: [Available middleware](available_middleware.md)

src/Resources/doc/response_streaming.md

@@ -23,3 +23,5 @@ class MyController extends ContainerAware
     }
 }
 ```
+
+Next section: [Configuration reference](configuration_reference.md)