Blackfire PHP SDK

Starting in version 1.14.0, a build can contain multiple scenarios. This changed the way builds are structured and initialized.

Deprecated items:

• Class \Blackfire\Build (replaced by \Blackfire\Build\Scenario)
• Methods createBuild, endBuild, and addJobInBuild (replaced by startScenario, closeScenario, and addJobInScenario)

New items:

• Classes \Blackfire\Build\Build and \Blackfire\Build\Scenario
• Methods startBuild, closeBuild, startScenario, closeScenario, and addJobInScenario

Migration Example:

From the legacy single-scenario approach:

$build = $blackfire->createBuild('Blackfire dev', array('title' => 'Legacy build'));
$config = new \Blackfire\Profile\Configuration();
$config->setBuild($build);
$probe = $blackfire->createProbe($config);
// ... profile code ...
$blackfire->endProbe($probe);
$report = $blackfire->endBuild($build);

To the new multi-scenario approach:

$build = $blackfire->startBuild('Blackfire dev', array('title' => 'My build'));
$scenario = $blackfire->startScenario($build, array('title' => 'Test documentation'));
$config = new \Blackfire\Profile\Configuration();
$config->setScenario($scenario);
$probe = $blackfire->createProbe($config);
// ... profile code ...
$blackfire->endProbe($probe);
$report = $blackfire->closeScenario($scenario);
$blackfire->closeBuild($build);

<?php

require_once __DIR__.'/vendor/autoload.php';

$blackfire = new /Blackfire/Client();

// create a build
$build = $blackfire->startBuild('Blackfire dev', array(
    'title' => 'My build',
    'trigger_name' => 'PHP',
));

// create a scenario
$scenario = $blackfire->startScenario($build, array(
    'title' => 'Test documentation',
    'external_id' => 'c:my-scenario',
    'external_parent_id' => 'b:my-scenario',
));

// create a configuration
$config = new /Blackfire/Profile/Configuration();
$config->setScenario($scenario);

// create as many profiles as you need
$probe = $blackfire->createProbe($config);

// some PHP code you want to profile
echo strlen('Hello !');

$blackfire->endProbe($probe);

// end the build and fetch the report
$report = $blackfire->closeScenario($scenario);

$blackfire->closeBuild($build);

A probe allows you to instrument a specific execution flow to collect performance data.

1. Create a probe: Use createProbe() which returns a Blackfire\Probe instance. You can optionally pass a Blackfire\Profile\Configuration to customize the profile (e.g., setting a title).
2. End a probe: Use endProbe(Probe $probe) to stop the instrumentation. This method returns a Blackfire\Profile object, which represents the collected data.

Note: createProbe enables the probe by default unless the second argument is set to false.

use Blackfire\Client;
use Blackfire\Profile\Configuration as ProfileConfiguration;

$client = new Client();

// 1. Create the probe
$config = new ProfileConfiguration();
$config->setTitle('My Custom Profile');
$probe = $client->createProbe($config);

// ... run your code to be profiled ...

// 2. End the probe and get the profile
$profile = $client->endProbe($probe);

The blackfire-io-proxy.php script is a CLI tool used to inspect the HTTP traffic between profiled servers and Blackfire's servers. It acts as a middleman, logging requests and responses to standard output.

Setup Instructions

To use the proxy effectively, you must reconfigure your Blackfire settings to route traffic through it:

1. Agent Configuration: Set the collector setting of your Blackfire agent to http://127.0.0.1:8383.
2. CLI Tool Configuration: Set the endpoint setting of your Blackfire CLI tool to http://127.0.0.1:8383.
3. Run the Proxy: Start this script in a dedicated terminal window to view the intercepted traffic.

Usage

Run the script from the command line. It accepts two optional positional arguments:

1. backendEndpoint: The destination server (defaults to https://blackfire.io).
2. upstreamHost: The local address the proxy should listen on (defaults to 127.0.0.1:8383).

Traffic Inspection Features

• Visual Indicators: The proxy uses color-coded prefixes in the output:
  • -> (Red): Outgoing traffic (from the client/agent towards Blackfire).
  • <- (Green): Incoming traffic (from Blackfire towards the client/agent).
• Data Decoding:
  • JSON: Automatically pretty-prints JSON payloads.
  • Compressed Data: If the zlib extension is enabled, the proxy will automatically inflate and display compressed data. If zlib is missing, it will notify you that data is compressed and suggest enabling the extension.

# Basic usage (listening on default 127.0.0.1:8383)
php bin/blackfire-io-proxy.php

# Custom backend and custom listening port
php bin/blackfire-io-proxy.php https://custom-blackfire-endpoint.com 127.0.0.1:9000