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.

v7.3.1 2018-06-10 11:09 UTC

README

Requirements | Installation | Usage | Plugins | Events | Features | Suggestions | Contributing | License

Symfony GuzzleBundle

Total Downloads Monthly Downloads Latest Stable Version Build Status Scrutinizer Score License SensioLabsInsight

This bundle integrates Guzzle 6.x into Symfony. Guzzle is a PHP framework for building RESTful web service clients.

GuzzleBundle follows semantic versioning. Read more on semver.org.

Requirements

Installation

Command line:

To install this bundle, run the command below and you will get the latest version by Packagist.

composer require eightpoints/guzzle-bundle
composer.json

To use the newest (maybe unstable) version please add following into your composer.json:

{
    "require": {
        "eightpoints/guzzle-bundle": "dev-master"
    }
}
Using Symfony Flex

Also it is possible to install bundle through Symfony Flex. It works for Symfony 3.3 and higher.
Bundle will be added to kernel file and default configuration will be created automatically.

composer config extra.symfony.allow-contrib true
composer require eightpoints/guzzle-bundle

Note: for symfony 3.3 and 3.4 you should install symfony/flex by yourself. From 4.0 it is included be default.

Usage

Load bundle in AppKernel.php:
new EightPoints\Bundle\GuzzleBundle\EightPointsGuzzleBundle()
Configuration in config.yml:
eight_points_guzzle:
    # (de)activate logging/profiler; default: %kernel.debug%
    logging: true

    clients:
        api_payment:
            base_url: "http://api.domain.tld"
            
            # NOTE: This option makes Guzzle Client as lazy (https://symfony.com/doc/master/service_container/lazy_services.html)
            lazy: true # Default `false`
            
            # Handler class to be used for the client
            handler: 'GuzzleHttp\Handler\MockHandler'

            # guzzle client options (full description here: https://guzzle.readthedocs.org/en/latest/request-options.html)
            # NOTE: "headers" option is not accepted here as it is provided as described above.
            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:
                    sslversion: 1 # or !php/const:CURL_HTTP_VERSION_1_0 for symfony >= 3.2

                timeout: 30

            # plugin settings
            plugin: ~

        api_crm:
            base_url: "http://api.crm.tld"
            options:            
                headers:
                    Accept: "application/json"

        ...

Allowed options: headers, allow_redirects, auth, query, curl, cert, connect_timeout, debug, decode_content, delay, form_params, multipart, sink, http_errors, expect, ssl_key, stream, synchronous, timeout, verify, cookies, proxy, version. All these settings are optional.
Description for all options and examples of parameters can be found here.

Install assets (if it's not performed automatically):
# for symfony >= 3.0
bin/console assets:install

# for symfony < 3.0
app/console assets:install

Using services in controller (eight_points_guzzle.client.api_crm represents the client name of the yaml config and is an instance of GuzzleHttp\Client):

/** @var \GuzzleHttp\Client $client */
$client   = $this->get('eight_points_guzzle.client.api_crm');
$response = $client->get('/users');

Plugins

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

Usage

Symfony 2.x and 3.x

All plugins will be activated/connected through bundle constructor in AppKernel, like this:

new EightPoints\Bundle\GuzzleBundle\EightPointsGuzzleBundle([
    new Gregurco\Bundle\GuzzleBundleOAuth2Plugin\GuzzleBundleOAuth2Plugin(),
])

Symfony 4

The registration of bundles was changed in Symfony 4 and now you have to change src/Kernel.php to achieve the same functionality.
Find next lines:

foreach ($contents as $class => $envs) {
    if (isset($envs['all']) || isset($envs[$this->environment])) {
        yield new $class();
    }
}

and replace them by:

foreach ($contents as $class => $envs) {
    if (isset($envs['all']) || isset($envs[$this->environment])) {
        if ($class === \EightPoints\Bundle\GuzzleBundle\EightPointsGuzzleBundle::class) {
            yield new $class([
                new \Gregurco\Bundle\GuzzleBundleOAuth2Plugin\GuzzleBundleOAuth2Plugin(),
            ]);
        } else {
            yield new $class();
        }
    }
}

Known and Supported Plugins

Events

Handling events. Events are dispatched before and after the request to the remote host.

Listening To Events

    <service id="listenerID" class="Your\ListenerClass\That\Implements\GuzzleEventListenerInterface">  
        <tag name="kernel.event_listener" event="eight_points_guzzle.pre_transaction" method="onPreTransaction" service="servicename"/>  
    </service>  

Your event Listener, or Subscriber MUST implement GuzzleBundle\Events\GuzzleEventListenerInterface.
Events dispatched are eight_points_guzzle.pre_transaction, eight_points_guzzle.post_transaction.
The service on the tag, is so that if you have multiple REST endpoints you can define which service a particular listener is interested in.

Read more here.

Features

Symfony Debug Toolbar / Profiler

Debug Logs

Symfony logs

All requests are logged into symfony default logger (@logger service) with next 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 message format by overriding eight_points_guzzle.symfony_log_formatter.pattern parameter. See allowed variables here.

Suggestions

Adding aliases: If you want to use different names for provided services you can use aliases. This is a good idea if you don't want have any dependency to guzzle in your service name.

services:
   crm.client:
       alias: eight_points_guzzle.client.api_crm

Use Guzzle MockHandler in tests : If you want to mock api calls, you can force the clients to use the Guzzle MockHandler instead of the default one.

eight_points_guzzle:
    clients:
        api_payment:
            base_url: "http://api.domain.tld"
            handler: 'GuzzleHttp\Handler\MockHandler'

Contributing

👍 If you would like to contribute to the project, please read the CONTRIBUTING.md.

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

🎉 Thanks to the contributors who participated in this project.

Learn more

License

This bundle is released under the MIT license