CakePHP Integration

The Perfbase CakePHP plugin provides automatic profiling for HTTP requests and console commands. Supports CakePHP 4.4+ and 5.x.

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

Load the plugin in your application:

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

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'),
],

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 routes and 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 gets a span named http.{METHOD}.{identifier} using the matched route template when available (e.g., http.GET./articles/:id rather than http.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 gets a span named console.{command} (e.g., console.migrate). 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 requests 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 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 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.