Yii 3 Integration

The Perfbase Yii 3 package provides profiling for PSR-15 HTTP middleware and Symfony Console events used by Yii 3 applications. Supports PHP 8.2 through 8.4.

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 ships Yii config-plugin files for params, DI, web middleware services, and console events. You still add the HTTP middleware to your application pipeline where profiling should wrap request handling.

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 config-plugin DI files register PerfbaseHttpMiddleware in the 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 uses the stable span name http. The route template is recorded in the action attribute when available (e.g., GET /api/users/{id}). Route metadata is extracted from PSR-7 request attributes (routePattern, route, routeName, controller, action).

Automatic attributes

Console command profiling

The package registers console event listeners through Yii config-plugin in standard Yii 3 apps. 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 uses the stable span name artisan. The command name is recorded in the action attribute and 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 extension trace span is started.

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.

Current scope

Yii 3 support does not include queue or worker profiling, scheduler-specific integration, custom buffering/retries, or Yii-specific profiling UI. HTTP middleware is registered as a service but is not inserted into your app’s pipeline automatically.