You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: integrations/symfony-bundle.rst
+63-20Lines changed: 63 additions & 20 deletions
Original file line number
Diff line number
Diff line change
@@ -1,9 +1,13 @@
1
1
Symfony Bundle
2
2
==============
3
3
4
-
This bundle integrate HTTPlug with the Symfony framework. The bundle helps to register services for all your clients and makes sure all the configuration is in one place. The bundle also feature a toolbar plugin with information about your requests.
4
+
This bundle integrate HTTPlug with the Symfony framework. The bundle helps to
5
+
register services for all your clients and makes sure all the configuration is
6
+
in one place. The bundle also feature a toolbar plugin with information about
7
+
your requests.
5
8
6
-
This guide explains how to configure HTTPlug in the Symfony framework. See the :doc:`../httplug/tutorial` for examples how to use HTTPlug in general.
9
+
This guide explains how to configure HTTPlug in the Symfony framework. See the
10
+
:doc:`../httplug/tutorial` for examples how to use HTTPlug in general.
7
11
8
12
Installation
9
13
````````````
@@ -24,7 +28,8 @@ Install the HTTPlug bundle with composer and enable it in your AppKernel.php.
24
28
);
25
29
}
26
30
27
-
You will find all available configuration at the :doc:`full configuration </integrations/symfony-full-configuration>` page.
When using a client configured with ``HttplugBundle``, you will get debug information in the web debug toolbar. It will tell you how many request were made and how many of those that were successful or not. It will also show you detailed information about each request.
62
+
When using a client configured with ``HttplugBundle``, you will get debug
63
+
information in the web debug toolbar. It will tell you how many request were
64
+
made and how many of those that were successful or not. It will also show you
65
+
detailed information about each request.
58
66
59
-
The web profiler page will show you lots of information about the request and also how different plugins changes the message. See example screen shots below.
67
+
The web profiler page will show you lots of information about the request and
68
+
also how different plugins changes the message. See example screen shots below.
@@ -72,22 +81,29 @@ The web profiler page will show you lots of information about the request and al
72
81
73
82
|clearfloat|
74
83
75
-
The body of the HTTP messages is not captured by default because of performance reasons. Turn this on by changing the ``captured_body_length`` configuration.
84
+
The body of the HTTP messages is not captured by default because of performance
85
+
reasons. Turn this on by changing the ``captured_body_length`` configuration.
76
86
77
87
.. code-block:: yaml
78
88
79
89
httplug:
80
90
toolbar:
81
91
captured_body_length: 1000# Capture the first 1000 chars of the HTTP body
82
92
83
-
The toolbar is automatically turned off when ``kernel.debug = false``. You can also disable the toolbar by configuration.
93
+
The toolbar is automatically turned off when ``kernel.debug = false``. You can
94
+
also disable the toolbar by configuration.
84
95
85
96
.. code-block:: yaml
86
97
87
98
httplug:
88
99
toolbar: false
89
100
90
-
You can configure the bundle to show debug information for clients found with discovery. You may also force a specific client to be found when a third party library is using discovery. The configuration below makes sure the client with service id ``httplug.clients.my_guzzle5`` is returned when calling ``HttpClientDiscovery::find()`` . It does also make sure to show debug info for asynchronous clients.
101
+
You can configure the bundle to show debug information for clients found with
102
+
discovery. You may also force a specific client to be found when a third party
103
+
library is using discovery. The configuration below makes sure the client with
104
+
service id ``httplug.clients.my_guzzle5`` is returned when calling
105
+
``HttpClientDiscovery::find()`` . It does also make sure to show debug info for
106
+
asynchronous clients.
91
107
92
108
.. note::
93
109
@@ -103,14 +119,21 @@ You can configure the bundle to show debug information for clients found with di
103
119
client: 'httplug.clients.my_guzzle5'
104
120
async_client: 'auto'
105
121
106
-
For normal clients, the auto discovery debug info is enabled by default. For async clients, debug is not enabled by default to avoid errors when using the bundle with a client that can not do async. To get debug information for async clients, set ``discovery.async_client`` to ``'auto'`` or an explicit client.
122
+
For normal clients, the auto discovery debug info is enabled by default. For
123
+
async clients, debug is not enabled by default to avoid errors when using the
124
+
bundle with a client that can not do async. To get debug information for async
125
+
clients, set ``discovery.async_client`` to ``'auto'`` or an explicit client.
107
126
108
-
You can turn off all interaction of the bundle with auto discovery by setting the value of ``discovery.client`` to ``false``.
127
+
You can turn off all interaction of the bundle with auto discovery by setting
128
+
the value of ``discovery.client`` to ``false``.
109
129
110
130
Discovery of Factory Classes
111
131
````````````````````````````
112
132
113
-
If you want the bundle to automatically find usable factory classes, install and enable ``puli/symfony-bundle``. If you do not want use auto discovery, you need to specify all the factory classes for you client. The following example show how you configure factory classes using Guzzle:
133
+
If you want the bundle to automatically find usable factory classes, install
134
+
and enable ``puli/symfony-bundle``. If you do not want use auto discovery, you
135
+
need to specify all the factory classes for you client. The following example
136
+
show how you configure factory classes using Guzzle:
114
137
115
138
.. code-block:: yaml
116
139
@@ -126,7 +149,9 @@ If you want the bundle to automatically find usable factory classes, install and
126
149
Configure Clients
127
150
`````````````````
128
151
129
-
You can configure your clients with default options. These default values will be specific to you client you are using. The clients are later registered as services.
152
+
You can configure your clients with default options. These default values will
153
+
be specific to you client you are using. The clients are later registered as
154
+
services.
130
155
131
156
.. code-block:: yaml
132
157
@@ -153,7 +178,10 @@ You can configure your clients with default options. These default values will b
153
178
// will be the same as ``httplug.client.my_guzzle5``
The bundle has client factory services that you can use to build your client. If you need a very custom made client you could create your own factory service implementing ``Http\HttplugBundle\ClientFactory\ClientFactory``. The built-in services are:
181
+
The bundle has client factory services that you can use to build your client.
182
+
If you need a very custom made client you could create your own factory service
183
+
implementing ``Http\HttplugBundle\ClientFactory\ClientFactory``. The built-in
184
+
services are:
157
185
158
186
* ``httplug.factory.curl``
159
187
* ``httplug.factory.buzz``
@@ -165,9 +193,12 @@ The bundle has client factory services that you can use to build your client. If
165
193
Plugins
166
194
```````
167
195
168
-
Clients can have plugins. Generic plugins from ``php-http/plugins`` (e.g. retry or redirect) can be configured globally. You can tell the client which of those plugins to use, as well as custom plugins that you configured a service for.
196
+
Clients can have plugins. Generic plugins from ``php-http/plugins`` (e.g. retry
197
+
or redirect) can be configured globally. You can tell the client which of those
198
+
plugins to use, as well as custom plugins that you configured a service for.
169
199
170
-
Additionally you can configure any of the ``php-http/plugins`` specifically on a client. For some plugins this is the only place where they can be configured.
200
+
Additionally you can configure any of the ``php-http/plugins`` specifically on
201
+
a client. For some plugins this is the only place where they can be configured.
171
202
The order in which you specify the plugins **does** matter.
172
203
173
204
.. code-block:: yaml
@@ -205,7 +236,9 @@ The order in which you specify the plugins **does** matter.
205
236
Authentication
206
237
``````````````
207
238
208
-
You can configure a client with authentication. Valid authentication types are ``basic``, ``bearer``, ``service`` and ``wsse``. See more examples at the :doc:`full configuration </integrations/symfony-full-configuration>`.
239
+
You can configure a client with authentication. Valid authentication types are
240
+
``basic``, ``bearer``, ``service`` and ``wsse``. See more examples at the
@@ -226,7 +259,8 @@ You can configure a client with authentication. Valid authentication types are `
226
259
Special HTTP Clients
227
260
````````````````````
228
261
229
-
If you want to use the ``FlexibleHttpClient`` or ``HttpMethodsClient`` from the ``php-http/message`` package you may specify that on the client configuration.
262
+
If you want to use the ``FlexibleHttpClient`` or ``HttpMethodsClient`` from the
263
+
``php-http/message`` package you may specify that on the client configuration.
230
264
231
265
.. code-block:: yaml
232
266
@@ -278,9 +312,18 @@ List of Services
278
312
Usage for Reusable Bundles
279
313
``````````````````````````
280
314
281
-
Rather than code against specific HTTP clients, you want to use the HTTPlug ``Client`` interface. To avoid building your own infrastructure to define services for the client, simply ``require: php-http/httplug-bundle`` in your bundles ``composer.json``. You SHOULD provide a configuration option to specify the which HTTP client service to use for each of your services. This option should default to ``httplug.client``. This way, the default case needs no additional configuration for your users, but they have the option of using specific clients with each of your services.
282
-
283
-
The only steps they need is ``require`` one of the adapter implementations in their projects ``composer.json`` and instantiating the ``HttplugBundle`` in their kernel.
315
+
Rather than code against specific HTTP clients, you want to use the HTTPlug
316
+
``Client`` interface. To avoid building your own infrastructure to define
317
+
services for the client, simply ``require: php-http/httplug-bundle`` in your
318
+
bundles ``composer.json``. You SHOULD provide a configuration option to specify
319
+
which HTTP client service to use for each of your services. This option should
320
+
default to ``httplug.client``. This way, the default case needs no additional
321
+
configuration for your users, but they have the option of using specific
322
+
clients with each of your services.
323
+
324
+
The only steps they need is ``require`` one of the adapter implementations in
325
+
their projects ``composer.json`` and instantiating the ``HttplugBundle`` in
0 commit comments