CakePHP Integration

The Perfbase CakePHP plugin provides automatic HTTP request profiling and CakePHP console command profiling. HTTP profiling works on CakePHP 4.4+ and 5.x. Console command profiling is automatic on CakePHP 5 and opt-in on CakePHP 4 through ProfiledCommand.

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 CakePHP plugin:

composer require perfbase/cakephp:^1.0

Load the plugin in your application:

// src/Application.php
public function bootstrap(): void
{
    parent::bootstrap();
    $this->addPlugin(\Perfbase\CakePHP\PerfbasePlugin::class);
}

Configuration

Configure the plugin via Configure::write() in your app config, or by creating a config/perfbase.php file in your application:

// config/app_local.php
'Perfbase' => [
    'enabled' => true,
    'api_key' => env('PERFBASE_API_KEY'),
    'sample_rate' => 0.1,
],

Or as a standalone config file:

// config/perfbase.php
return [
    'enabled' => true,
    'api_key' => env('PERFBASE_API_KEY'),
    'sample_rate' => 0.1,
];

Configuration is resolved in three layers (later wins): package defaults → your config/perfbase.php → Configure::write('Perfbase', ...) calls.

All options

Include and exclude filters

Control which HTTP requests and console commands are profiled:

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

Pattern types

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

HTTP patterns are tested against multiple representations of the request: the route template (e.g., /articles/:id), the controller/action path, the raw URI, and {METHOD} {path}.

HTTP middleware

The plugin adds PerfbaseMiddleware to the middleware queue automatically when profiling is enabled. 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 controller.
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 matched route template is recorded in the action attribute when available (e.g., GET /articles/:id rather than GET /articles/42).

Automatic attributes

Console command profiling

CakePHP 5: automatic

On CakePHP 5, all commands are profiled automatically via Command.beforeExecute and Command.afterExecute event listeners. No code changes required.

Each command uses the stable span name artisan. The command name is recorded in the action attribute, and the exit code is recorded as an attribute.

CakePHP 4: opt-in

CakePHP 4 does not emit command lifecycle events, so profiling is opt-in. Extend ProfiledCommand instead of Command:

use Perfbase\CakePHP\Command\ProfiledCommand;

class ImportCommand extends ProfiledCommand
{
    public function execute(Arguments $args, ConsoleIo $io): ?int
    {
        // Your command logic, profiled automatically
        return self::CODE_SUCCESS;
    }
}

Sample rate

The sample rate controls what fraction of eligible HTTP requests and console commands are profiled:

'Perfbase' => [
    '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 unit of work 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 plugin detects this gracefully and silently disables profiling.

Using the SDK directly

Access the SDK via PerfbaseLocator for manual profiling:

use Perfbase\CakePHP\Support\PerfbaseLocator;

$perfbase = PerfbaseLocator::get();
if ($perfbase) {
    $perfbase->setAttribute('batch_size', (string) $count);
}

See the PHP SDK docs for the full API reference.

Current scope

CakePHP queue profiling is not wired in v1. Transport, retry behavior, and buffering are delegated to the PHP SDK rather than reimplemented in this plugin.