README

Laravel Octane bridge for perftools/php-profiler.

This package wires the core profiler into the Laravel Octane request lifecycle.

It starts profiling on RequestReceived and stops profiling on RequestTerminated.

Scope

• Laravel Octane only.
• No FPM, queue worker, or Artisan profiling lifecycle is provided here.
• Runtime failures are logged and do not break the request.

Requirements

• PHP 8.2+
• illuminate/support ^10.0, ^11.0, ^12.0, or ^13.0
• laravel/octane ^2.3
• perftools/php-profiler ^1.4

Installation

Install the package into a Laravel Octane application:

composer require perftools/php-profiler-laravel

Service provider

Laravel package discovery registers the provider automatically:

Xhgui\Profiler\Laravel\XhguiProfilerServiceProvider

If you disable discovery, register that provider manually.

Configuration

Publish the package config:

php artisan vendor:publish --tag=xhgui-config

The package owns the enabled toggle and ships a default file-based saver example. Profiling is disabled by default, so enabling it is an explicit opt-in. The resulting config/xhgui.php is passed to the core profiler.

Default config shape:

<?php

use Xhgui\Profiler\Profiler;

return [
    'enabled' => env('XHGUI_ENABLED', false),
    'save.handler' => env('XHGUI_SAVE_HANDLER', Profiler::SAVER_FILE),
    'save.handler.file' => [
        'filename' => env('XHGUI_SAVE_FILE', storage_path('logs/xhgui/profile.jsonl')),
    ],
];

You can replace the saver-related settings with any config supported by the core perftools/php-profiler library.

If you set the profiler.request_context_provider key in config/xhgui.php before profiling starts, for example:

use App\Profiling\AppRequestContextProvider;

return [
    'profiler.request_context_provider' => new AppRequestContextProvider(),
];

The package ignores it. Laravel Octane integration always injects its own OctaneRequestContextProvider so request context is captured from the current Octane request.

Under Octane, profiler configuration is treated as static for the lifetime of a worker. Restart Octane workers after changing config/xhgui.php for new profiler settings to take effect.

Contributing

See CONTRIBUTING.md for local development setup and verification, package behavior notes, and scope reminders.