From 87d2d80ea2167f70c413223329de9217857cb838 Mon Sep 17 00:00:00 2001 From: David Buchmann Date: Fri, 12 Aug 2016 15:50:02 +0200 Subject: [PATCH] document configuring plugins on client --- integrations/symfony-bundle.rst | 19 +++++++- integrations/symfony-full-configuration.rst | 51 +++++++++++++++------ 2 files changed, 54 insertions(+), 16 deletions(-) diff --git a/integrations/symfony-bundle.rst b/integrations/symfony-bundle.rst index 80e3d90..2f8774f 100644 --- a/integrations/symfony-bundle.rst +++ b/integrations/symfony-bundle.rst @@ -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 @@ -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" + - header_defaults: + "X-FOO": bar + - authentication: + acme_basic: + type: 'basic' + username: 'my_username' + password: 'p4ssw0rd' Authentication diff --git a/integrations/symfony-full-configuration.rst b/integrations/symfony-full-configuration.rst index 6089a95..b98ba7f 100644 --- a/integrations/symfony-full-configuration.rst +++ b/integrations/symfony-full-configuration.rst @@ -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' @@ -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' 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 @@ -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"]