Skip to content

Commit b8971bd

Browse files
NyholmNyholm
committed
Updated docs for the bundle
1 parent 7c2dbb9 commit b8971bd

File tree

4 files changed

+163
-74
lines changed

4 files changed

+163
-74
lines changed

‎assets/img/debug-toolbar.png

6.99 KB
Loading

‎integrations/index.rst

+1
Original file line numberDiff line numberDiff line change
@@ -6,3 +6,4 @@ HTTPlug provides the following framework integrations:
66
.. toctree::
77

88
symfony-bundle
9+
symfony-full-configuration

‎integrations/symfony-bundle.rst

+87-74
Original file line numberDiff line numberDiff line change
@@ -1,74 +1,60 @@
11
Symfony Bundle
22
==============
33

4-
The usage documentation is split into two parts. First we explain how to configure the bundle in an application. The second part is for developing reusable Symfony bundles that depend on an HTTP client defined by the Httplug interface.
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.
55

6-
For information how to write applications with the services provided by this bundle, have a look at the [Httplug documentation](http://docs.php-http.org).
6+
Usage
7+
`````
78

9+
.. code-block:: yaml
810
9-
Use in Applications
10-
-------------------
11+
httplug:
12+
plugins:
13+
logger: ~
14+
clients:
15+
acme:
16+
factory: 'httplug.factory.guzzle6'
17+
plugins: ['httplug.plugin.logger']
18+
config:
1119
12-
Custom services
13-
```````````````
20+
.. code-block:: php
1421
15-
+----------------------------------+---------------------------------------------------------------------+
16-
| Service id | Description |
17-
+==================================+=====================================================================+
18-
| httplug.message_factory | Service* that provides the `Http\Message\MessageFactory` |
19-
+----------------------------------+---------------------------------------------------------------------+
20-
| httplug.uri_factory | Service* that provides the `Http\Message\UriFactory` |
21-
+----------------------------------+---------------------------------------------------------------------+
22-
| httplug.stream_factory | Service* that provides the `Http\Message\StreamFactory` |
23-
+----------------------------------+---------------------------------------------------------------------+
24-
| httplug.client.[name] | | This is your Httpclient that you have configured. |
25-
| | | With the configuration below the name would be `acme_client`. |
26-
+----------------------------------+---------------------------------------------------------------------+
27-
| httplug.client | This is the first client configured or a client named `default`. |
28-
+----------------------------------+---------------------------------------------------------------------+
29-
| | httplug.plugin.content_length | | These are plugins that are enabled by default. |
30-
| | httplug.plugin.decoder | | These services are not public and may only be used when configure |
31-
| | httplug.plugin.error | | HttpClients or other services. |
32-
| | httplug.plugin.logger | |
33-
| | httplug.plugin.redirect | |
34-
| | httplug.plugin.retry | |
35-
| | httplug.plugin.stopwatch | |
36-
+----------------------------------+---------------------------------------------------------------------+
37-
| | httplug.plugin.cache | | These are plugins that are disabled by default. |
38-
| | httplug.plugin.cookie | | They need to be configured before they can be used. |
39-
| | httplug.plugin.history | | These services are not public and may only be used when configure |
40-
| | | HttpClients or other services. |
41-
+----------------------------------+---------------------------------------------------------------------+
22+
$request = $this->container->get('httplug.message_factory')->createRequest('GET', 'http://example.com');
23+
$response = $this->container->get('httplug.client.acme')->sendRequest($request);
4224
43-
\* *These services are always an alias to another service. You can specify your own service or leave the default, which is the same name with `.default` appended. The default services in turn use the service discovery mechanism to provide the best available implementation. You can specify a class for each of the default services to use instead of discovery, as long as those classes can be instantiated without arguments.*
25+
Installation
26+
````````````
4427

28+
Install the Httplug bundle with composer and enabled it in your AppKernel.php.
4529

46-
If you need a more custom setup, define the services in your application configuration and specify your service in the `main_alias` section. For example, to add authentication headers, you could define a service that decorates the service `httplug.client.default` with a plugin that injects the authentication headers into the request and configure `httplug.main_alias.client` to the name of your service.
30+
.. code-block:: bash
4731
48-
.. code-block:: yaml
32+
$ composer require php-http/httplug-bundle
4933
50-
httplug:
51-
clients:
52-
acme_client: # This is the name of the client
53-
factory: 'httplug.factory.guzzle6'
54-
55-
main_alias:
56-
client: httplug.client.default
57-
message_factory: httplug.message_factory.default
58-
uri_factory: httplug.uri_factory.default
59-
stream_factory: httplug.stream_factory.default
60-
classes:
61-
# uses discovery if not specified
62-
client: ~
63-
message_factory: ~
64-
uri_factory: ~
65-
stream_factory: ~
34+
.. code-block:: php
35+
36+
public function registerBundles()
37+
{
38+
$bundles = array(
39+
// ...
40+
new Http\HttplugBundle\HttplugBundle(),
41+
);
42+
}
6643
44+
You will find all available configuration at the :doc:`full configuration </integrations/symfony-full-configuration>` page.
6745

68-
Configuration without auto discovery
69-
````````````````````````````````````
46+
Web debug toolbar
47+
`````````````````
48+
.. image:: assets/img/debug-toolbar.png
49+
:align: right
50+
:width: 120px
7051

71-
By default we use Puli to auto discover factories. If you do not want to use auto discovery you could use the following configuration (Guzzle):
52+
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.
53+
54+
Discovery of factory classes
55+
````````````````````````````
56+
57+
If you want to automatically find our factory classes you should install and enabled ``puli/symfony-bundle``. If you do not want use auto discovery you should specify all the factory classes for you client. The following example show how you configure factory classes using Guzzle.
7258

7359
.. code-block:: yaml
7460
@@ -80,10 +66,11 @@ By default we use Puli to auto discover factories. If you do not want to use aut
8066
stream_factory: Http\Message\StreamFactory\GuzzleStreamFactory
8167
8268
69+
8370
Configure your client
8471
`````````````````````
8572

86-
You can configure your clients with some good default options. The clients are later registered as services.
73+
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.
8774

8875
.. code-block:: yaml
8976
@@ -109,64 +96,90 @@ You can configure your clients with some good default options. The clients are l
10996
$httpClient = $this->container->get('httplug.client.my_guzzle5');
11097
$httpClient = $this->container->get('httplug.client.acme');
11198
99+
// will be the same as ``httplug.client.my_guzzle5``
100+
$httpClient = $this->container->get('httplug.client');
101+
112102
113103
Plugins
114104
```````
115105

116-
You can configure the clients with plugins.
106+
You can configure the clients with plugins. You can choose to use a built in plugin in the ``php-http/plugins`` package or provide a plugin of your own. The order of the specified plugin does matter.
117107

118108
.. code-block:: yaml
119109
120110
// services.yml
121111
acme_plugin:
122-
class: Acme\Plugin\MyCustonPlugin
123-
arguments: ["%api_key%"]
112+
class: Acme\Plugin\MyCustomPlugin
113+
arguments: ["%some_parameter%"]
124114
125115
.. code-block:: yaml
126116
127117
// config.yml
128-
httpug:
118+
httplug:
129119
plugins:
130120
cache:
131121
cache_pool: 'my_cache_pool'
132122
clients:
133123
acme:
134124
factory: 'httplug.factory.guzzle6'
135-
plugins: ['acme_plugin', 'httplug.plugin.cache', ''httplug.plugin.retry']
136-
config:
137-
base_uri: 'http://google.se/'
125+
plugins: ['acme_plugin', 'httplug.plugin.cache', 'httplug.plugin.retry']
138126
139127
140128
Authentication
141129
``````````````
142130

131+
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>`.
132+
143133
.. code-block:: yaml
144134
145135
// config.yml
146-
httpug:
136+
httplug:
147137
plugins:
148138
authentication:
149-
my_basic:
150-
type: 'basic'
151-
username: 'my_username'
152-
password: 'p4ssw0rd'
153139
my_wsse:
154140
type: 'wsse'
155141
username: 'my_username'
156142
password: 'p4ssw0rd'
157-
my_brearer:
158-
type: 'bearer'
159-
token: 'authentication_token_hash'
160-
my_service:
161-
type: 'service'
162-
service: 'my_authentication_service'
163143
164144
clients:
165145
acme:
166146
factory: 'httplug.factory.guzzle6'
167147
plugins: ['httplug.plugin.authentication.my_wsse']
168148
169149
150+
List of services
151+
````````````````
152+
153+
+----------------------------------+---------------------------------------------------------------------+
154+
| Service id | Description |
155+
+==================================+=====================================================================+
156+
| httplug.message_factory | Service* that provides the `Http\Message\MessageFactory` |
157+
+----------------------------------+---------------------------------------------------------------------+
158+
| httplug.uri_factory | Service* that provides the `Http\Message\UriFactory` |
159+
+----------------------------------+---------------------------------------------------------------------+
160+
| httplug.stream_factory | Service* that provides the `Http\Message\StreamFactory` |
161+
+----------------------------------+---------------------------------------------------------------------+
162+
| httplug.client.[name] | | This is your HttpClient that you have configured. |
163+
| | | With the configuration below the name would be `acme_client`. |
164+
+----------------------------------+---------------------------------------------------------------------+
165+
| httplug.client | This is the first client configured or a client named `default`. |
166+
+----------------------------------+---------------------------------------------------------------------+
167+
| | httplug.plugin.content_length | | These are plugins that are enabled by default. |
168+
| | httplug.plugin.decoder | | These services are not public and may only be used when configure |
169+
| | httplug.plugin.error | | HttpClients or other services. |
170+
| | httplug.plugin.logger | |
171+
| | httplug.plugin.redirect | |
172+
| | httplug.plugin.retry | |
173+
| | httplug.plugin.stopwatch | |
174+
+----------------------------------+---------------------------------------------------------------------+
175+
| | httplug.plugin.cache | | These are plugins that are disabled by default. |
176+
| | httplug.plugin.cookie | | They need to be configured before they can be used. |
177+
| | httplug.plugin.history | | These services are not public and may only be used when configure |
178+
| | | HttpClients or other services. |
179+
+----------------------------------+---------------------------------------------------------------------+
180+
181+
\* *These services are always an alias to another service. You can specify your own service or leave the default, which is the same name with `.default` appended. The default services in turn use the service discovery mechanism to provide the best available implementation. You can specify a class for each of the default services to use instead of discovery, as long as those classes can be instantiated without arguments.*
182+
170183

171184
Use for Reusable Bundles
172185
------------------------

‎integrations/symfony-full-configuration.rst

+75
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
Full configuration
2+
==================
3+
4+
This page shows an example of all configuration values provided by the bundle.
5+
6+
.. code-block:: yaml
7+
8+
// config.yml
9+
httplug:
10+
main_alias:
11+
client: httplug.client.default
12+
message_factory: httplug.message_factory.default
13+
uri_factory: httplug.uri_factory.default
14+
stream_factory: httplug.stream_factory.default
15+
classes:
16+
# uses discovery if not specified
17+
client: ~
18+
message_factory: ~
19+
uri_factory: ~
20+
stream_factory: ~
21+
22+
plugins:
23+
authentication:
24+
my_basic:
25+
type: 'basic'
26+
username: 'my_username'
27+
password: 'p4ssw0rd'
28+
my_wsse:
29+
type: 'wsse'
30+
username: 'my_username'
31+
password: 'p4ssw0rd'
32+
my_bearer:
33+
type: 'bearer'
34+
token: 'authentication_token_hash'
35+
my_service:
36+
type: 'service'
37+
service: 'my_authentication_service'
38+
cache:
39+
enabled: true
40+
cache_pool: 'my_cache_pool'
41+
stream_factory: 'httplug.stream_factory'
42+
config:
43+
default_ttl: 3600
44+
respect_cache_headers: true
45+
cookie:
46+
enabled: true
47+
cookie_jar: my_cookie_jar
48+
decoder:
49+
enabled: true
50+
use_content_encoding: true
51+
history:
52+
enabled: true
53+
journal: my_journal
54+
logger:
55+
enabled: true
56+
logger: 'logger'
57+
formatter: null
58+
redirect:
59+
enabled: true
60+
preserve_header: true
61+
use_default_for_multiple: true
62+
retry:
63+
enabled: true
64+
retry: 1
65+
stopwatch:
66+
enabled: true
67+
stopwatch: 'debug.stopwatch'
68+
clients:
69+
acme:
70+
factory: 'httplug.factory.guzzle6'
71+
plugins: ['httplug.plugin.authentication.my_wsse', 'httplug.plugin.cache', 'httplug.plugin.retry']
72+
config:
73+
base_uri: 'http://google.se/'
74+
# more options to the guzzle 6 constructor
75+

0 commit comments

Comments
 (0)