Skip to content

Commit 087dd68

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

File tree

3 files changed

+158
-70
lines changed

3 files changed

+158
-70
lines changed

‎assets/img/debug-bar.png

6.99 KB
Loading

‎integrations/symfony-bundle.rst

Lines changed: 83 additions & 70 deletions
Original file line numberDiff line numberDiff line change
@@ -5,70 +5,56 @@ The usage documentation is split into two parts. First we explain how to configu
55

66
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).
77

8+
Usage
9+
`````
810

9-
Use in Applications
10-
-------------------
11+
.. code-block:: yaml
1112
12-
Custom services
13-
```````````````
13+
httplug:
14+
plugins:
15+
logger: ~
16+
clients:
17+
acme:
18+
factory: 'httplug.factory.guzzle6'
19+
plugins: ['httplug.plugin.logger']
20+
config:
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+
.. code-block:: php
4223
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.*
24+
$request = $this->container->get('httplug.message_factory')->createRequest('GET', 'http://example.com');
25+
$response = $this->container->get('httplug.client.acme')->sendRequest($request);
4426
27+
Installation
28+
````````````
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+
Install the Httplug Bundle with composer and enabled it in your AppKernel.php.
4731

48-
.. code-block:: yaml
32+
.. code-block:: bash
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+
$ composer require php-http/httplug-bundle
35+
36+
.. code-block:: php
37+
38+
public function registerBundles()
39+
{
40+
$bundles = array(
41+
// ...
42+
new Http\HttplugBundle\HttplugBundle(),
43+
);
44+
}
45+
46+
Web debug toolbar
47+
`````````````````
48+
.. image:: assets/img/debug-bar.png
49+
:align: right
50+
:width: 120px
6651

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.
6753

68-
Configuration without auto discovery
69-
````````````````````````````````````
54+
Discovery of factory classes
55+
````````````````````````````
7056

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):
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,18 +96,21 @@ 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
@@ -132,41 +122,64 @@ You can configure the clients with plugins.
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
146136
httpug:
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

Lines changed: 75 additions & 0 deletions
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+
httpug:
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_brearer:
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 constuctor
75+

0 commit comments

Comments
 (0)