Skip to content

document configuring plugins on client #142

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Aug 15, 2016
Merged

document configuring plugins on client #142

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 17 additions & 2 deletions integrations/symfony-bundle.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -165,7 +165,10 @@ The bundle has client factory services that you can use to build your client. If
Plugins
```````

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

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.
The order in which you specify the plugins **does** matter.

.. code-block:: yaml

Expand All @@ -184,7 +187,19 @@ You can configure the clients with plugins. You can choose to use a built in plu
clients:
acme:
factory: 'httplug.factory.guzzle6'
plugins: ['acme_plugin', 'httplug.plugin.cache', 'httplug.plugin.retry']
plugins:
- 'acme_plugin'
- 'httplug.plugin.cache'
- 'httplug.plugin.retry'
- add_host:
host: "http://localhost:8000"
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why new lines here?
I suggest:

plugins:
    - 'acme_plugin'
    - add_host:
           host: "http://localhost:8000"

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also add option `replace``

- header_defaults:
"X-FOO": bar
- authentication:
acme_basic:
type: 'basic'
username: 'my_username'
password: 'p4ssw0rd'


Authentication
Expand Down
51 changes: 37 additions & 14 deletions integrations/symfony-full-configuration.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ This page shows an example of all configuration values provided by the bundle.
uri_factory: ~
stream_factory: ~

plugins:
plugins: # Global plugin configuration. Plugins need to be explicitly added to clients.
authentication:
my_basic:
type: 'basic'
Expand All @@ -36,38 +36,30 @@ This page shows an example of all configuration values provided by the bundle.
type: 'service'
service: 'my_authentication_service'
cache:
enabled: true
cache_pool: 'my_cache_pool'
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good

stream_factory: 'httplug.stream_factory'
config:
default_ttl: 3600
respect_cache_headers: true
cookie:
enabled: true
cookie_jar: my_cookie_jar
decoder:
enabled: true
use_content_encoding: true
history:
enabled: true
journal: my_journal
logger:
enabled: true
logger: 'logger'
formatter: null
redirect:
enabled: true
preserve_header: true
use_default_for_multiple: true
retry:
enabled: true
retry: 1
stopwatch:
enabled: true
stopwatch: 'debug.stopwatch'

toolbar:
enabled: true
profiling:
enabled: true # Defaults to kernel.debug
formatter: null # Defaults to \Http\Message\Formatter\FullHttpMessageFormatter
captured_body_length: 0

Expand All @@ -78,11 +70,42 @@ This page shows an example of all configuration values provided by the bundle.
clients:
acme:
factory: 'httplug.factory.guzzle6'
plugins: ['httplug.plugin.authentication.my_wsse', 'httplug.plugin.cache', 'httplug.plugin.retry']
flexible_client: false # Can only be true if http_methods_client is false
http_methods_client: false # Can only be true if flexible_client is false
config:
# Options to the Guzzle 6 constructor
verify: false
timeout: 2
# more options to the Guzzle 6 constructor

plugins:
# Can reference a globally configured plugin service
- 'httplug.plugin.authentication.my_wsse'
# Can configure a plugin customized for this client
- cache:
cache_pool: 'my_other_pool'
config:
default_ttl: 120
# Can configure plugins that can not be configured globally
- add_host:
# Host name including protocol and optionally the port number, e.g. https://api.local:8000
host: http://localhost:80 # Required
# Whether to replace the host if request already specifies it
replace: false
# Append headers to the request. If the header already exists the value will be appended to the current value.
- header_append:
# Keys are the header names, values the header values
headers:
'X-FOO': bar # contrary to default symfony behaviour, hyphens "-" are NOT translated to underscores "_" for the headers.
# Set header to default value if it does not exist.
- header_defaults:
# Keys are the header names, values the header values
headers:
'X-FOO': bar
# Set headers to requests. If the header does not exist it wil be set, if the header already exists it will be replaced.
- header_set:
# Keys are the header names, values the header values
headers:
'X-FOO': bar
# Remove headers from requests.
- header_remove:
# List of header names to remove
headers: ["X-FOO"]