README

Perfbase for Laravel

Laravel integration for Perfbase.

This package is a thin adapter over perfbase/php-sdk. It wires Laravel request, console, and queue lifecycles into the SDK and leaves trace transport, submission, and extension handling to the shared SDK.

What it profiles

HTTP requests when the Perfbase middleware is installed
Artisan commands through Laravel console events
Queue jobs through Laravel queue events
Manual custom spans through the Perfbase facade or injected SDK client

Requirements

PHP 7.4 to 8.5
Laravel 8.x, 9.x, 10.x, 11.x, 12.x, or 13.x
ext-json
ext-zlib
ext-perfbase

Installation

Install the package from Packagist:

composer require perfbase/laravel:^1.0

Install the native Perfbase extension if it is not already available:

bash -c "$(curl -fsSL https://cdn.perfbase.com/install.sh)"

Restart PHP-FPM, Octane workers, Horizon workers, or your web server after installing the extension.

Publish the config file:

php artisan vendor:publish --tag="perfbase-config"

Add the minimum environment variables:

PERFBASE_ENABLED=true
PERFBASE_API_KEY=your_api_key_here
PERFBASE_SAMPLE_RATE=0.1

HTTP middleware

HTTP profiling is enabled only when the middleware is present.

For Laravel 8 to 10, add it to app/Http/Kernel.php:

protected $middleware = [
    // ...
    \Perfbase\Laravel\Middleware\PerfbaseMiddleware::class,
];

Or attach it to a middleware group:

protected $middlewareGroups = [
    'web' => [
        // ...
        \Perfbase\Laravel\Middleware\PerfbaseMiddleware::class,
    ],
];

For Laravel 11+, register it in bootstrap/app.php:

use Illuminate\Foundation\Application;
use Illuminate\Foundation\Configuration\Middleware;
use Perfbase\Laravel\Middleware\PerfbaseMiddleware;

return Application::configure(dirname(__DIR__))
    ->withMiddleware(function (Middleware $middleware) {
        $middleware->append(PerfbaseMiddleware::class);
    })
    ->create();

Console and queue profiling do not need middleware. They are wired through the package service provider.

Configuration

Published config lives at config/perfbase.php.

return [
    'enabled' => env('PERFBASE_ENABLED', false),
    'debug' => env('PERFBASE_DEBUG', false),
    'log_errors' => env('PERFBASE_LOG_ERRORS', true),
    'api_key' => env('PERFBASE_API_KEY'),
    'sample_rate' => env('PERFBASE_SAMPLE_RATE', 0.1),
    'timeout' => env('PERFBASE_TIMEOUT', 5),
    'proxy' => env('PERFBASE_PROXY'),
    'flags' => env('PERFBASE_FLAGS', \Perfbase\SDK\FeatureFlags::DefaultFlags),
    'include' => [
        'http' => ['.*'],
        'console' => ['.*'],
        'queue' => ['.*'],
    ],
    'exclude' => [
        'http' => [],
        'console' => ['queue:work'],
        'queue' => [],
    ],
];

Environment variables

Variable	Default	Purpose
`PERFBASE_ENABLED`	`false`	Global on/off switch
`PERFBASE_API_KEY`	`null`	Perfbase API key
`PERFBASE_SAMPLE_RATE`	`0.1`	Sampling rate from `0.0` to `1.0`
`PERFBASE_DEBUG`	`false`	Re-throw profiling exceptions
`PERFBASE_LOG_ERRORS`	`true`	Log profiling failures when debug is off
`PERFBASE_TIMEOUT`	`5`	Trace submission timeout in seconds
`PERFBASE_PROXY`	`null`	Optional outbound proxy
`PERFBASE_FLAGS`	`FeatureFlags::DefaultFlags`	Perfbase extension feature flags

Feature flags

use Perfbase\SDK\FeatureFlags;

'flags' => FeatureFlags::DefaultFlags;
'flags' => FeatureFlags::AllFlags;
'flags' => FeatureFlags::TrackCpuTime | FeatureFlags::TrackPdo;

Common flags:

UseCoarseClock
TrackCpuTime
TrackMemoryAllocation
TrackPdo
TrackHttp
TrackCaches
TrackMongodb
TrackElasticsearch
TrackQueues
TrackAwsSdk
TrackFileOperations
TrackFileCompilation
TrackFileDefinitions
TrackExceptions

Include and exclude filters

Filters are split by context: http, console, and queue.

'include' => [
    'http' => ['GET /api/*', 'POST /checkout'],
    'console' => ['migrate*', 'app:*'],
    'queue' => ['App\\Jobs\\Important*'],
],

'exclude' => [
    'http' => ['GET /health*', '_debugbar/*'],
    'console' => ['queue:work', 'horizon:*'],
    'queue' => ['App\\Jobs\\NoisyDebugJob'],
],

Supported filter styles:

Wildcards like GET /api/*
Regex patterns like /^POST \/checkout/
Command patterns like queue:*
Job class patterns like App\\Jobs\\*
Controller or action strings matched through Laravel's string matcher

How it behaves

HTTP requests

PerfbaseMiddleware creates an HttpTraceLifecycle for the current request.

Recorded attributes include:

source=http
action
http_method
http_url
http_status_code
user_ip
user_agent
user_id when available
environment
app_version
hostname
php_version

Console commands

The service provider listens to Laravel console events and creates a ConsoleTraceLifecycle.

Recorded attributes include:

source=console
action
exit_code
exception when present
environment
app_version
hostname
php_version

Queue jobs

The service provider listens to queue worker events and creates a QueueTraceLifecycle.

Recorded attributes include:

source=queue
action
queue
connection
exception when present
environment
app_version
hostname
php_version

Manual spans

Use the facade when you want custom spans inside your own application code:

use Perfbase\Laravel\Facades\Perfbase;

Perfbase::startTraceSpan('custom-operation', [
    'operation_type' => 'data_processing',
    'record_count' => '1000',
]);

Perfbase::setAttribute('processing_method', 'batch');
Perfbase::setAttribute('memory_usage', (string) memory_get_usage());

try {
    processLargeDataset();
    Perfbase::setAttribute('status', 'success');
} catch (\Exception $e) {
    Perfbase::setAttribute('status', 'error');
    Perfbase::setAttribute('error_message', $e->getMessage());
    throw $e;
} finally {
    Perfbase::stopTraceSpan('custom-operation');
}

$result = Perfbase::submitTrace();

if (!$result->isSuccess()) {
    logger()->warning('Perfbase trace submission failed', [
        'status' => $result->getStatus(),
        'message' => $result->getMessage(),
        'status_code' => $result->getStatusCode(),
    ]);
}

Note that Perfbase trace attributes are string values. Cast integers and booleans before passing them to setAttribute().

Dependency injection

You can inject the SDK client directly:

use Perfbase\SDK\Perfbase;

class DataProcessingService
{
    /** @var Perfbase */
    private $perfbase;

    public function __construct(Perfbase $perfbase)
    {
        $this->perfbase = $perfbase;
    }

    public function processData(array $data): array
    {
        $this->perfbase->startTraceSpan('data-processing', [
            'record_count' => (string) count($data),
            'data_type' => 'user_records',
        ]);

        try {
            $result = $this->performProcessing($data);
            $this->perfbase->setAttribute('processed_count', (string) count($result));
            return $result;
        } finally {
            $this->perfbase->stopTraceSpan('data-processing');
        }
    }
}

User-specific request profiling

If your authenticated user model implements Perfbase\Laravel\Interfaces\ProfiledUser, HTTP request profiling will respect shouldBeProfiled().

use Perfbase\Laravel\Interfaces\ProfiledUser;

class User extends Authenticatable implements ProfiledUser
{
    public function shouldBeProfiled(): bool
    {
        return $this->isAdmin() || $this->isBetaTester();
    }
}

If the authenticated user does not implement ProfiledUser, the package falls back to normal request filtering rules.

Facade methods

Method	Description
`startTraceSpan($name, $attributes = [])`	Start a named span
`stopTraceSpan($name)`	Stop a named span
`setAttribute($key, $value)`	Add a string attribute to the current trace
`setFlags($flags)`	Change extension feature flags
`submitTrace()`	Submit trace data and return a `SubmitResult`
`getTraceData($spanName = '')`	Get raw trace data
`reset()`	Clear the current trace session
`isExtensionAvailable()`	Check whether the native extension is loaded

Error handling

The package is designed to fail open in normal operation. When profiling cannot start or trace submission fails, your Laravel request, command, or job should continue running.

Use PERFBASE_DEBUG=true if you want profiling exceptions to surface during local development.

Testing

In application tests, it is often simplest to disable profiling:

<env name="PERFBASE_ENABLED" value="false"/>

You can also mock the facade:

use Perfbase\Laravel\Facades\Perfbase;

public function test_something()
{
    Perfbase::shouldReceive('startTraceSpan')->once();
    Perfbase::shouldReceive('stopTraceSpan')->once();

    // ...
}

Troubleshooting

Extension not loaded

php -m | grep perfbase
php --ini
bash -c "$(curl -fsSL https://cdn.perfbase.com/install.sh)"

High overhead

Lower PERFBASE_SAMPLE_RATE
Use FeatureFlags::UseCoarseClock
Disable feature flags you do not need
Narrow your include filters and expand your exclude filters

Documentation

Full documentation is available at perfbase.com/docs.

Docs: perfbase.com/docs
Issues: github.com/perfbaseorg/laravel/issues
Support: support@perfbase.com

License

Apache-2.0. See LICENSE.txt.

perfbase / laravel

Maintainers

Package info

Statistics

Security

README

Perfbase for Laravel

What it profiles

Requirements

Installation

HTTP middleware

Configuration

Environment variables

Feature flags

Include and exclude filters

How it behaves

HTTP requests

Console commands

Queue jobs

Manual spans

Dependency injection

User-specific request profiling

Facade methods

Error handling

Testing

Troubleshooting

Extension not loaded

High overhead

Documentation

License