CodeIgniter 4 Integration

The Perfbase CodeIgniter 4 package provides automatic profiling for HTTP requests and Spark CLI commands. Supports CodeIgniter 4.3.8+.

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 CodeIgniter 4 package:

composer require perfbase/codeigniter4

Run the install command to publish the config file and register the filter:

php spark perfbase:install

This publishes app/Config/Perfbase.php and patches your app/Config/Filters.php to add the perfbase filter alias and global before/after entries.

Configuration

Add your API key to .env and enable profiling:

perfbase.enabled = true
perfbase.apiKey = your-api-key

Or configure in the published app/Config/Perfbase.php:

namespace Config;

use Perfbase\CodeIgniter4\Config\Perfbase as BasePerfbase;

class Perfbase extends BasePerfbase
{
    public bool $enabled = true;
    public string $apiKey = 'your-api-key';
}

Environment variables (set in .env) take precedence over class property defaults.

All options

Include and exclude filters

Control which routes and commands are profiled via env variables or config properties:

perfbase.includeHttp = *
perfbase.excludeHttp = /health,/ready,/metrics
perfbase.includeConsole = *
perfbase.excludeConsole =

Or in app/Config/Perfbase.php:

public array $includeHttp = ['*'];
public array $excludeHttp = ['/health', '/ready'];
public array $includeConsole = ['*'];
public array $excludeConsole = [];

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 pattern (e.g., users/(:num)), {METHOD} {routePattern}, the controller class, the method name, and Controller::method.

HTTP profiling

HTTP requests are profiled via a CI4 filter registered as a global before/after filter. The filter:

1. Before: creates a profiling lifecycle using the matched route pattern and starts the trace span.
2. After: records the HTTP status code, stops the span, and submits the trace.

If an uncaught exception occurs (skipping the after phase), the package’s exception handler intercepts it, finalizes the trace, and then delegates to CI4’s normal exception handling.

Each request gets a span named http.{METHOD}.{identifier} using the route pattern when available (e.g., http.GET./users/(:num) rather than http.GET./users/42).

Automatic attributes

Spark CLI profiling

Spark commands are profiled automatically via command lifecycle events. The package decorates CI4’s Commands service to fire profiling events before and after each command.

Each command gets a span named console.{command} (e.g., console.migrate, console.db:seed). The exit code and any exceptions are recorded as attributes.

Uses the console include/exclude filter context.

User identification

The package resolves user IDs for HTTP traces using this priority:

1. Custom resolver: set perfbase.userResolver to a class name implementing UserResolverInterface, or a CI4 service name.
2. CodeIgniter Shield: if Shield is installed, the authenticated user is detected automatically.
3. Request property: falls back to $request->user if it exists.

Custom resolver example

namespace App\Support;

use CodeIgniter\HTTP\RequestInterface;
use Perfbase\CodeIgniter4\Contracts\UserResolverInterface;

class MyUserResolver implements UserResolverInterface
{
    public function resolve(RequestInterface $request): ?string
    {
        return session('user_id') ? (string) session('user_id') : null;
    }
}

Configure it:

perfbase.userResolver = App\Support\MyUserResolver

Sample rate

The sample rate controls what fraction of requests are profiled:

perfbase.sampleRate = 1.0    # Profile everything (development)
perfbase.sampleRate = 0.1    # 10% of requests (production)
perfbase.sampleRate = 0.01   # 1% of requests (high-traffic)

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

Doctor command

Verify your installation is correctly configured:

php spark perfbase:doctor

This checks: profiling enabled, API key set, SDK initialization, PHP extension availability, filter alias registered, global before/after filters, Shield detection, and worker-mode compatibility.

Error handling

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

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