Guzzle

Guzzle is a PHP HTTP client that makes it easy to send HTTP requests and trivial to integrate with web services. Integrating Blackfire with Guzzle lets lets you profile programmatically your websites, HTTP APIs, or web services.

Installation

First, add Blackfire PHP SDK as a dependency on your project.

Caution

This document assumes Guzzle version 6+ that requires PHP 5.5+. For earlier versions, the same principles apply, but the syntax might be different.

Profiling

The Blackfire PHP SDK provides a Guzzle middleware that eases the profiling of requests made via Guzzle:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
use GuzzleHttp\Client as GuzzleClient;
use Blackfire\Client as BlackfireClient;
use Blackfire\ClientConfiguration;
use Blackfire\Bridge\Guzzle\Middleware as BlackfireMiddleware;

$blackfire = new BlackfireClient(new ClientConfiguration($clientId, $clientToken));

$guzzle = new GuzzleClient([
    // useful if you want to simulate a user experience
    'cookies' => true,
]);

$guzzle->getConfig('handler')->push(BlackfireMiddleware::create($blackfire), 'blackfire');

Whenever you want to profile a request, set the blackfire option to true:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
use Blackfire\Client as BlackfireClient;
use Blackfire\ClientConfiguration;
use GuzzleHttp\Client as GuzzleClient;
use Blackfire\Bridge\Guzzle\Middleware as BlackfireMiddleware;

$blackfire = new BlackfireClient(new ClientConfiguration($clientId, $clientToken));

$guzzle = new GuzzleClient(['cookies' => true]);
$guzzle->getConfig('handler')->push(BlackfireMiddleware::create($blackfire), 'blackfire');

$response = $guzzle->request('GET', 'https://www.symfony.com/blog/', array(
    'blackfire' => true
));

// get the profile for the request
$profile = $blackfire->getProfile($response->getHeader('X-Blackfire-Profile-Uuid')[0]);

If you execute this script, a profile will be created on your Blackfire account and of course, tests defined in your .blackfire.yml if any will be executed as well. Note that the profile UUID is stored in the X-Blackfire-Profile-Uuid response header by the Blackfire middleware.

If you want to better control the profile configuration, like the number of samples or the title of the profile, pass a \Blackfire\Profile\Configuration instance as the blackfire option value:

1
2
3
4
5
6
7
$config = new \Blackfire\Profile\Configuration();
$config->setSamples(10);
$config->setTitle('Blog Home');

$response = $client->request('GET', 'https://www.symfony.com/blog/', array(
    'blackfire' => $config,
));

When running this script, you will get one profile which will be the aggregation of the 10 HTTP requests executed.

Learn more about profiling configuration settings in the PHP SDK documentation.

Builds

Note

This feature is only available to our Premium and Enterprise users.

As Guzzle provides great support for HTTP, you can create almost any HTTP request you can think of, but more importantly, you can simulate complex user interactions. Writing scenarios with Guzzle is a powerful alternative to the scenarios defined in a .blackfire.yml file.

To generate a report from a scenario created with Guzzle, store all profiles in a build:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
// create a build
$build = $blackfire->createBuild('Symfony Prod', array('title' => 'Build from Goutte'));

// create a configuration
$config = new \Blackfire\Profile\Configuration();
$config->setBuild($build);

// set the Profile and Job name
$config->setTitle('Blog Home');

// make a profiled request
$client->request('GET', 'https://www.symfony.com/blog/', array(
    'blackfire' => $config
));

// get the profile for the request
$profile = $blackfire->getProfile($response->getHeader('X-Blackfire-Profile-Uuid')[0]);

// end the build and fetch the report
// the build contains one profile
$report = $blackfire->endBuild($build);

Note how we set the build on the configuration passed Guzzle.