Yii 2 Integration

The Perfbase Yii 2 package provides automatic profiling for HTTP requests and console commands via Yii’s application event system. Supports Yii 2.0.45+.

Installation

Install the Perfbase PHP extension first. This is what does the actual profiling:

bash -c "$(curl -fsSL https://cdn.perfbase.com/install.sh)"

Then install the Yii 2 package:

composer require perfbase/yii2

Configuration

Register the component and add it to the bootstrap array in your application config:

// config/web.php
return [
    'bootstrap' => ['perfbase'],
    'components' => [
        'perfbase' => [
            'class' => \Perfbase\Yii2\PerfbaseComponent::class,
            'enabled' => true,
            'api_key' => 'your-api-key',
        ],
    ],
];

For console command profiling, add the same config to config/console.php.

Important: The bootstrap entry is required. It triggers bootstrap($app) on the component, which wires the event listeners that drive profiling.

All options

Include and exclude filters

Control which routes and commands are profiled:

'perfbase' => [
    // ...
    'include' => [
        'http' => ['*'],                        // All routes (default)
        'console' => ['*'],                     // All commands (default)
    ],
    'exclude' => [
        'http' => ['/health', '/debug/*'],
        'console' => ['migrate/*'],
    ],
],

Pattern types

• Glob patterns: /api/*, /admin/users/* (matched via fnmatch())
• Regex patterns: /^GET \/api\// (wrapped in forward slashes)
• Catch-all: * or .* matches everything

HTTP patterns are tested against: the URL path, the resolved route (e.g., /site/index), the controller and action (app\controllers\UserController::view), {METHOD} {path}, {METHOD} {route}, and the raw requested route.

Console patterns are tested against the resolved command name (e.g., migrate/up).

HTTP profiling

HTTP requests are profiled automatically via Yii 2 application events, with no middleware, behaviors, or filters needed.

The component listens to two events:

1. EVENT_BEFORE_ACTION: creates a profiling lifecycle using the resolved action and starts the trace span.
2. EVENT_AFTER_REQUEST: records the HTTP status code, captures any exception from the error handler, stops the span, and submits the trace.

A shutdown event listener provides a fallback to ensure traces are submitted even on fatal errors.

Each request gets a span named http.{METHOD}.{route} using Yii’s resolved route when available (e.g., http.GET./site/index, http.POST./api/user/create). Query strings are never included.

Automatic attributes

Console command profiling

Console commands are profiled automatically using the same event mechanism. The command name is resolved from the action’s unique ID, falling back to the requested route or unknown.

Each command gets a span named console.{command} (e.g., console.migrate/up). The exit code is recorded as an attribute.

Uses the console include/exclude filter context.

Sample rate

The sample rate controls what fraction of requests are profiled:

'sample_rate' => 1.0,    // Profile everything (development)
'sample_rate' => 0.1,    // 10% of requests (production)
'sample_rate' => 0.01,   // 1% of requests (high-traffic)

When a request isn’t sampled, no profiling overhead is incurred.

Error handling

Profiling never crashes your application. In production (debug: false), all profiling errors are caught and optionally logged via error_log(). In development (debug: true), errors are thrown so you can catch configuration issues early.

If the Perfbase PHP extension is not installed, the component detects this gracefully and silently disables profiling.

Using the SDK directly

Access the SDK through the component for manual attribute setting:

$client = Yii::$app->perfbase->getClientProvider()->getClient();
if ($client) {
    $client->setAttribute('user_type', 'admin');
}

See the PHP SDK docs for the full API reference.