Prerequisites | Installation | Configuration | Usage | Plugins | Events | Features | Suggestions | Contributing | Learn more | License
This bundle integrates Guzzle 6.x into Symfony. Guzzle is a PHP library for building RESTful web service clients.
GuzzleBundle follows semantic versioning. Read more on semver.org.
- PHP 7.1 or higher
- Symfony 4.x or 5.x
To install this bundle, run the command below on the command line and you will get the latest stable version from Packagist.
composer require eightpoints/guzzle-bundleNote: this bundle has a Symfony Flex Recipe to automatically register and configure this bundle into your symfony application.
If your project does not use Symfony Flex the following needs to be added to config/bundles.php manually:
<?php
return [
// other bundles here
EightPoints\Bundle\GuzzleBundle\EightPointsGuzzleBundle::class => ['all' => true],
];Guzzle clients can be configured in config/packages/eight_points_guzzle.yaml. For projects that use Symfony Flex this file is created
automatically upon installation of this bundle. For projects that don't use Symfony Flex this file should be created manually.
eight_points_guzzle:
# (de)activate logging/profiler; default: %kernel.debug%
logging: true
# configure when a response is considered to be slow (in ms); default 0 (disabled)
slow_response_time: 1000
clients:
payment:
base_url: 'http://api.payment.example'
# NOTE: This option marks this Guzzle Client as lazy (https://symfony.com/doc/master/service_container/lazy_services.html)
lazy: true # Default `false`
# guzzle client options (full description here: https://guzzle.readthedocs.org/en/latest/request-options.html)
options:
auth:
- acme # login
- pa55w0rd # password
headers:
Accept: 'application/json'
# Find proper php const, for example CURLOPT_SSLVERSION, remove CURLOPT_ and transform to lower case.
# List of curl options: http://php.net/manual/en/function.curl-setopt.php
curl:
!php/const:CURL_HTTP_VERSION_1_0: 1
timeout: 30
# plugin settings
plugin: ~
crm:
base_url: 'http://api.crm.tld'
options:
headers:
Accept: 'application/json'
# More clients herePlease refer to the Configuration Reference for a complete list of all options.
Guzzle clients configured through this bundle are available in the Symfony Dependency Injection container under the name
eight_points_guzzle.client.<name of client>. So for example a client configured in the configuration with name payment is available
as eight_points_guzzle.client.payment.
Suppose you have the following controller that requires a Guzzle Client:
<?php
namespace App\Controller;
use Guzzle\Client;
class ExampleController
{
public function __construct(Client $client)
{
$this->client = $client;
}
}Using manual wiring this controller can be wired as follows:
services:
my.example.controller:
class: App\Controller\ExampleController
arguments: ['@eight_points_guzzle.client.payment']For projects that use autowiring, please refer to our documentation on autowiring.
This bundle allows to register and integrate plugins to extend functionality of guzzle and this bundle.
In order to install a plugin, find the following lines in src/Kernel.php:
foreach ($contents as $class => $envs) {
if ($envs[$this->environment] ?? $envs['all'] ?? false) {
yield new $class();
}
}and replace them with the following:
foreach ($contents as $class => $envs) {
if ($envs[$this->environment] ?? $envs['all'] ?? false) {
if ($class === \EightPoints\Bundle\GuzzleBundle\EightPointsGuzzleBundle::class) {
yield new $class([
new \Gregurco\Bundle\GuzzleBundleOAuth2Plugin\GuzzleBundleOAuth2Plugin(),
]);
} else {
yield new $class();
}
}
}- gregurco/GuzzleBundleWssePlugin
- gregurco/GuzzleBundleCachePlugin
- gregurco/GuzzleBundleOAuth2Plugin
- neirda24/GuzzleBundleHeaderForwardPlugin
- neirda24/GuzzleBundleHeaderDisableCachePlugin
- EugenGanshorn/GuzzleBundleRetryPlugin
This bundle dispatches Symfony events right before a client makes a call and right after a client has made a call. There are two types of events dispatched every time; a generic event, that is dispatched regardless of which client is doing the request, and a client specific event, that is dispatched only to listeners specifically subscribed to events from a specific client. These events can be used to intercept requests to a remote system as well as responses from a remote system. In case a generic event listener and a client specific event listener both change a request/response, the changes from the client specific listener override those of the generic listener in case of a collision (both setting the same header for example).
In order to listen to these events you should create a listener and register that listener in the Symfony services configuration as usual:
services:
my_guzzle_listener:
class: App\Service\MyGuzzleBundleListener
tags:
# Listen for generic pre transaction event (will receive events for all clients)
- { name: 'kernel.event_listener', event: 'eight_points_guzzle.pre_transaction', method: 'onPreTransaction' }
# Listen for client specific pre transaction events (will only receive events for the "payment" client)
- { name: 'kernel.event_listener', event: 'eight_points_guzzle.pre_transaction.payment', method: 'onPrePaymentTransaction' }
- # Listen for generic post transaction event (will receive events for all clients)
- { name: 'kernel.event_listener', event: 'eight_points_guzzle.post_transaction', method: 'onPostTransaction' }
# Listen for client specific post transaction events (will only receive events for the "payment" client)
- { name: 'kernel.event_listener', event: 'eight_points_guzzle.post_transaction.payment', method: 'onPostPaymentTransaction' }For more information, read the docs on intercepting requests and responses.
All requests are logged to Symfony's default logger (@logger service) with the following (default) format:
[{datetime}] eight_points_guzzle.{log_level}: {method} {uri} {code}
Example:
[2017-12-01 00:00:00] eight_points_guzzle.INFO: GET http://api.domain.tld 200
You can change the message format by overriding the eight_points_guzzle.symfony_log_formatter.pattern parameter.
For all options please refer to Guzzle's MessageFormatter.
In case your project uses manual wiring it is recommended to create aliases for the clients created with this bundle to get easier service names and also to make it easier to switch to other implementations in the future, might the need arise.
services:
crm.client: '@eight_points_guzzle.client.crm'In case your project uses autowiring this suggestion does not apply.
👍 If you would like to contribute to this bundle, please read CONTRIBUTING.md.
Join our Slack channel on Symfony Devs for discussions, questions and more: #8p-guzzlebundle.
🎉 Thanks to all contributors who participated in this project.
- Autowiring Clients
- Configuration Reference
- Disable throwing exceptions on HTTP errors (4xx and 5xx responses)
- Environment variables integration
- How to create a single-file plugin
- How to redefine class used for clients
- Intercept request and response
This bundle is released under the MIT license.