eightpoints/guzzle-bundle

Integrates Guzzle into Symfony2, comes with WSSE Plugin for RESTful Interfaces

v7.2.1 2017-11-17 14:23 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"

            # 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.

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

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

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

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.

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

Contributing

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

🎉 Thanks to the contributors who participated in this project.

License

This bundle is released under the MIT license