Using a service builder

The best way to instantiate Guzzle web service clients is to let Guzzle handle building the clients for you using a ServiceBuilder. A ServiceBuilder is responsible for creating concrete client objects based on configuration settings and helps to manage credentials for different environments.

You don't have to use a service builder, but they help to decouple your application from concrete classes and help to share configuration data across multiple clients. Consider the following example. Here we are creating two clients that require the same API public key and secret key. The clients are created using their factory() methods.

use MyService\FooClient;
use MyService\BarClient;

$foo = FooClient::factory(array(
    'key'    => 'abc',
    'secret' => '123',
    'custom' => 'and above all'
));

$bar = BarClient::factory(array(
    'key'    => 'abc',
    'secret' => '123',
    'custom' => 'listen to me'
));

The redundant specification of the API keys can be removed using a service builder.

use Guzzle\Service\Builder\ServiceBuilder;

$builder = ServiceBuilder::factory(array(
    'services' => array(
        'abstract_client' => array(
            'params' => array(
                'key'    => 'abc',
                'secret' => '123'
            )
        ),
        'foo' => array(
            'extends' => 'abstract_client',
            'class'   => 'MyService\FooClient',
            'params'  => array(
                'custom' => 'and above all'
            )
        ),
        'bar' => array(
            'extends' => 'abstract_client',
            'class'   => 'MyService\FooClient',
            'params'  => array(
                'custom' => 'listen to me'
            )
        )
    )
));

$foo = $builder->get('foo');
$bar = $builder->get('bar');

You can make managing your API keys even easier by saving the service builder configuration in a JSON format in a .json file.

Creating a service builder

A ServiceBuilder can source information from an array, an PHP include file that returns an array, or a JSON file.

use Guzzle\Service\Builder\ServiceBuilder;

// Source service definitions from a JSON file
$builder = ServiceBuilder::factory('services.json');

Sourcing data from an array

Data can be source from a PHP array. The array must contain an associative services array that maps the name of a client to the configuration information used by the service builder to create the client. Clients are given names which are used to identify how a client is retrieved from a service builder. This can be useful for using multiple accounts for the same service or creating development clients vs. production clients.

$services = array(
    'includes' => array(
        '/path/to/other/services.json',
        '/path/to/other/php_services.php'
    ),
    'services' => array(
        'abstract.foo' => array(
            'params' => array(
                'username' => 'foo',
                'password' => 'bar'
            )
        ),
        'bar' => array(
            'extends' => 'abstract.foo',
            'class'   => 'MyClientClass',
            'params'  => array(
                'other' => 'abc'
            )
        )
    )
);

A service builder configuration array contains two top-level array keys:

Key	Description
includes	Array of paths to JSON or PHP include files to include in the configuration.
services	Associative array of defined services that can be created by the service builder. Each service can contain the following keys: Key Description class The concrete class to instantiate that implements the Guzzle\Common\FromConfigInterface. extends The name of a previously defined service to extend from params Associative array of parameters to pass to the factory method of the service it is instantiated alias An alias that can be used in addition to the array key for retrieving a client from the service builder.

The first client defined, abstract.foo, is used as a placeholder of shared configuration values. Any service extending abstract.foo will inherit its params. As an example, this can be useful when clients share the same username and password.

The next client, bar, extends from abstract.foo using the extends attribute referencing the client from which to extend. Additional parameters can be merged into the original service definition when extending a parent service.

Important

Each client that you intend to instantiate must specify a class attribute that references the full class name of the client being created. The class referenced in the class parameter must implement a static factory() method that accepts an array or Guzzle\Common\Collection object and returns an instantiated object.

Sourcing from a PHP include

You can create service builder configurations using a PHP include file. This can be useful if you wish to take advantage of an opcode cache like APC to speed up the process of loading and processing the configuration. The PHP include file is the same format as an array, but you simply create a PHP script that returns an array and save the file with the .php file extension.

<?php return array('services' => '...');
// Saved as config.php

This configuration file can then be used with a service builder.

$builder = ServiceBuilder::factory('/path/to/config.php');

Sourcing from a JSON document

You can use JSON documents to serialize your service descriptions. The JSON format uses the exact same structure as the PHP array syntax, but it's just serialized using JSON.

{
    "includes": ["/path/to/other/services.json", "/path/to/other/php_services.php"],
    "services": {
        "abstract.foo": {
            "params": {
                "username": "foo",
                "password": "bar"
            }
        },
        "bar": {
            "extends": "abstract.foo",
            "class": "MyClientClass",
            "params": {
                "other": "abc"
            }
        }
    }
}

Referencing other clients in parameters

If one of your clients depends on another client as one of its parameters, you can reference that client by name by enclosing the client's reference key in {}.

{
    "services": {
        "token": {
            "class": "My\Token\TokenFactory",
            "params": {
                "access_key": "xyz"
            }
        },
        "client": {
            "class": "My\Client",
            "params": {
                "token_client": "{token}",
                "version": "1.0"
            }
        }
    }
}

When client is constructed by the service builder, the service builder will first create the token service and then inject the token service into client's factory method in the token_client parameter.

Retrieving clients from a service builder

Clients are referenced using a customizable name you provide in your service definition. The ServiceBuilder is a sort of multiton object-- it will only instantiate a client once and return that client for subsequent retrievals. Clients are retrieved by name (the array key used in the configuration) or by the alias setting of a service.

Here's an example of retrieving a client from your ServiceBuilder:

$client = $builder->get('foo');

// You can also use the ServiceBuilder object as an array
$client = $builder['foo'];

Creating throwaway clients

You can get a "throwaway" client (a client that is not persisted by the ServiceBuilder) by passing true in the second argument of ServiceBuilder::get(). This allows you to create a client that will not be returned by other parts of your code that use the service builder. Instead of passing true, you can pass an array of configuration settings that will override the configuration settings specified in the service builder.

// Get a throwaway client and overwrite the "custom" setting of the client
$foo = $builder->get('foo', array(
    'custom' => 'in this world there are rules'
));

Getting raw configuration settings

You can get the raw configuration settings provided to the service builder for a specific service using the getData($name) method of a service builder. This method will null if the service was not found in the service builder or an array of configuration settings if the service was found.

$data = $builder->getData('foo');
echo $data['key'] . "\n";
echo $data['secret'] . "\n";
echo $data['custom'] . "\n";

Adding a plugin to all clients

You can add a plugin to all clients created by a service builder using the addGlobalPlugin($plugin) method of a service builder and passing a Symfony\Component\EventDispatcher\EventSubscriberInterface object. The service builder will then attach each global plugin to every client as it is created. This allows you to, for example, add a LogPlugin to every request created by a service builder for easy debugging.

use Guzzle\Plugin\Log\LogPlugin;

// Add a debug log plugin to every client as it is created
$builder->addGlobalPlugin(LogPlugin::getDebugPlugin());

$foo = $builder->get('foo');
$foo->get('/')->send();
// Should output all of the data sent over the wire

Events emitted from a service builder

A Guzzle\Service\Builder\ServiceBuilder object emits the following events:

Event name	Description	Event data
service_builder.create_client	Called when a client is created	client: The created client object

use Guzzle\Common\Event;
use Guzzle\Service\Builder\ServiceBuilder;

$builder = ServiceBuilder::factory('/path/to/config.json');

// Add an event listener to print out each client client as it is created
$builder->getEventDispatcher()->addListener('service_builder.create_client', function (Event $e) {
    echo 'Client created: ' . get_class($e['client']) . "\n";
});

$foo = $builder->get('foo');
// Should output the class used for the "foo" client