diff --git a/README.md b/README.md index 06a72006..b9dc423a 100644 --- a/README.md +++ b/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 ------------ diff --git a/src/Resources/doc/available_middleware.md b/src/Resources/doc/available_middleware.md index 1b6121fb..36078611 100644 --- a/src/Resources/doc/available_middleware.md +++ b/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 %kernel.cache_dir%/my_cache_folder ``` + +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) diff --git a/src/Resources/doc/clients.md b/src/Resources/doc/clients.md index 582bfc3c..a71aac7e 100644 --- a/src/Resources/doc/clients.md +++ b/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: ``` + +Next section: [Registering new middleware](middleware.md) diff --git a/src/Resources/doc/configuration_reference.md b/src/Resources/doc/configuration_reference.md index f23a3dfd..5dd7336a 100644 --- a/src/Resources/doc/configuration_reference.md +++ b/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) diff --git a/src/Resources/doc/install.md b/src/Resources/doc/install.md new file mode 100644 index 00000000..7669d9fd --- /dev/null +++ b/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) diff --git a/src/Resources/doc/middleware.md b/src/Resources/doc/middleware.md index 33110290..cbeffb23 100644 --- a/src/Resources/doc/middleware.md +++ b/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 - + ``` @@ -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: ``` + +Next section: [Available middleware](available_middleware.md) diff --git a/src/Resources/doc/response_streaming.md b/src/Resources/doc/response_streaming.md index 442c610f..89694651 100644 --- a/src/Resources/doc/response_streaming.md +++ b/src/Resources/doc/response_streaming.md @@ -23,3 +23,5 @@ class MyController extends ContainerAware } } ``` + +Next section: [Configuration reference](configuration_reference.md) diff --git a/src/Resources/doc/service_descriptions.md b/src/Resources/doc/service_descriptions.md deleted file mode 100644 index 6d053ea8..00000000 --- a/src/Resources/doc/service_descriptions.md +++ /dev/null @@ -1,75 +0,0 @@ -Guzzle service definitions -========================== - -Importing definitions ---------------------- - -Since version `1.3`, CsaGuzzleBundle also integrates with `guzzlehttp/guzzle-services`. -This dependency is optional, so don't forget to add the library to your `composer.json`: - -```console - composer require guzzlehttp/services:~0.3 -``` - -In order to use a service description, the only thing necessary is to specify the description file path -when you configure your Guzzle client in the semantic configuration: - -```yml -csa_guzzle: - clients: - github_api: - base_url: https://api.github.com - defaults: - headers: - Accept: application/vnd.github.v3+json - description: /path/to/file.json -``` - -This will create a new service (`csa_guzzle.service.github`), which will use your description. You can use the service-enabled client the same way as you would use your normal client, in your controller or in another service: - -```php -get('csa_guzzle.service.github_api'); - // ... - } -} -``` - -Creating new description loaders --------------------------------- - -If you wish to add your own loader, to fetch a remote definition, you simply create a class implementing -`Symfony\Component\Config\Loader\LoaderInterface`, expose it as a service, and use the `csa_guzzle.description_loader` -dependency injection tag. - -```php - - - -``` diff --git a/src/Resources/doc/tests_mock_http_requests.md b/src/Resources/doc/tests_mock_http_requests.md deleted file mode 100644 index a1ff6fa0..00000000 --- a/src/Resources/doc/tests_mock_http_requests.md +++ /dev/null @@ -1,27 +0,0 @@ -Mock HTTP requests in tests -=========================== - -When running tests, you often want to disable real HTTP requests to your (or an external) API. -The CsaGuzzleBundle can record those requests to replay them in tests. - -First, enable the record mode, and play your tests: -i.e. in `config_test.yml` - -```yml -csa_guzzle: - mock: - storage_path: "%kernel.root_dir%/../features/fixtures/guzzle" - mode: record -``` - -Generated files can then be added to you VCS. -To use your mocks, change the mode to `replay` - -```yml -csa_guzzle: - mock: - storage_path: "%kernel.root_dir%/../features/fixtures/guzzle" - mode: replay -``` - -That's it !