eightpoints/guzzle-bundle

Integrates Guzzle 6.x, a PHP HTTP Client, into Symfony 2/3/4. Comes with easy and powerful configuration options and optional plugins.

Installs: 2 278 953

Dependents: 42

Suggesters: 4

Security: 0

Stars: 366

Watchers: 6

Forks: 69

Open Issues: 7

Type:symfony-bundle

v7.6.0 2019-10-02 11:16 UTC

README

Prerequisites | Installation | Configuration | Usage | Plugins | Events | Features | Suggestions | Contributing | Learn more | License

EightPoints GuzzleBundle for Symfony

Total Downloads Monthly Downloads Latest Stable Version Build Status Scrutinizer Score 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.

Prerequisites

  • PHP 7.1 or higher
  • Symfony 4.x or 5.x

Installation

Installing the bundle

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

Note: 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],
];

Installing the assets

This bundle comes with several assets required for integration with the Symfony Debug Toolbar. For projects based on symfony/skeleton this is done automatically by a composer script that runs after this bundle was installed. If this did not happen automatically (i.e. if the CSS in the Symfony Profiler for this bundle looks off), run the following command on the command line:

bin/console assets:install

Configuration

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 here

Please refer to the Configuration Reference for a complete list of all options.

Usage

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.

Plugins

This bundle allows to register and integrate plugins to extend functionality of guzzle and this bundle.

Installation

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();
        }
    }
}

Known and Supported Plugins

Events

This bundle dispatches Symfony events right before a client makes a call and right after a client has made a call. These events can be used to intercept requests to a remote system as well as responses from a remote system.

Listening To Events

In order to listen to these events you should create a listener that implements the GuzzleBundle\Events\GuzzleEventListenerInterface from this bundle and then register that listener in the Symfony services configuration as usual:

services:
    my_guzzle_listener:
        class: App\Service\MyGuzzleBundleListener
        tags:
            - { name: 'kernel.event_listener', event: 'eight_points_guzzle.pre_transaction', method: 'onPreTransaction', service: 'payment' }

Events dispatched are eight_points_guzzle.pre_transaction and eight_points_guzzle.post_transaction. The service attribute on the tag indicates to which client this listener should apply. Note that these listeners will receive all events from all clients; it is up to the listeners themselves to filter all incoming events and only process the events of the client they are interested in.

For more information, read the docs on intercepting requests and responses.

Features

Symfony Debug Toolbar / Profiler

Debug Logs

Logging

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.

Suggestions

Create aliases for clients

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.

Contributing

👍 If you would like to contribute to this bundle, please read CONTRIBUTING.md.

Slack Join our Slack channel on Symfony Devs for discussions, questions and more: #8p-guzzlebundle.

🎉 Thanks to all contributors who participated in this project.

Learn more

License

This bundle is released under the MIT license.