Yii 3 Integration

The Perfbase Yii 3 package provides automatic profiling for HTTP requests and console commands. Uses PSR-15 middleware for HTTP and Symfony event subscribers for console.

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 3 package:

composer require perfbase/yii3

The package includes a ConfigProvider that registers all services with the Yii 3 DI container automatically.

Configuration

Set your Perfbase parameters in the application params config:

// config/params.php
return [
    'perfbase' => [
        'enabled' => true,
        'api_key' => 'your-api-key',
    ],
];

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' => [],
    ],
],

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 request path, {METHOD} {path}, the route template (e.g., /api/users/{id}), {METHOD} {routeTemplate}, the route name, and the controller/action class.

Console patterns are tested against the command name.

HTTP middleware

Register the PSR-15 middleware in your application’s middleware pipeline:

use Perfbase\Yii3\Middleware\PerfbaseHttpMiddleware;

// In your middleware configuration
$middlewareDispatcher->addMiddleware(PerfbaseHttpMiddleware::class);

The ConfigProvider registers PerfbaseHttpMiddleware in the DI container, so it can be resolved by class name.

The middleware wraps each request in a profiling lifecycle:

1. Creates a profiling lifecycle and starts the trace span.
2. Executes the rest of the middleware stack and your handler.
3. Records the HTTP status code from the response.
4. Stops the span and submits the trace in a finally block, so traces are submitted even when exceptions occur.

Each request gets a span named http.{METHOD}.{identifier} using the route template when available (e.g., http.GET./api/users/{id}). Route metadata is extracted from PSR-7 request attributes (routePattern, route, routeName, controller, action).

Automatic attributes

Console command profiling

Register the event subscriber with your console application’s Symfony event dispatcher:

use Perfbase\Yii3\EventSubscriber\ConsoleProfilerSubscriber;

$dispatcher->addSubscriber($container->get(ConsoleProfilerSubscriber::class));

The subscriber hooks into three Symfony console events:

1. ConsoleEvents::COMMAND: creates a profiling lifecycle and starts the trace span.
2. ConsoleEvents::ERROR: records the exception.
3. ConsoleEvents::TERMINATE: records the exit code, stops the span, and submits the trace.

Each command gets a span named console.{command} (e.g., console.migrate/up). 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 middleware and subscriber detect this gracefully and silently disable profiling.

Using the SDK directly

Access the SDK through the DI container for manual attribute setting:

use Perfbase\Yii3\Support\PerfbaseClientProvider;

$client = $container->get(PerfbaseClientProvider::class)->getClient();
if ($client) {
    $client->setAttribute('operation', 'data-import');
}

See the PHP SDK docs for the full API reference.