/EightPointsGuzzleBundle

⛽️ Integrates Guzzle 6.x, a PHP HTTP Client, into Symfony

Primary LanguagePHPMIT LicenseMIT

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

Symfony GuzzleBundle

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

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"
    }
}

Note: we created Symfony Flex Recipe to speed up the installation of package.

Usage

Configuration in config.yml:
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:
        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"

        ...

Open Configuration Reference page to see the complete list of allowed options.

Install assets (if it's not performed automatically):
bin/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

Find next lines in src/Kernel.php:

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