Spiral Xhprof Profiler

Requirements

Make sure that your server is configured with following PHP version and extensions:

• PHP 8.1+
• Spiral framework 3.0+

Installation

To install the package:

composer require spiral/profiler

After package install you need to add bootloader from the package in your application.

use Spiral\RoadRunnerBridge\Bootloader as RoadRunnerBridge;

protected const LOAD = [
    // ...
    Spiral\Profiler\ProfilerBootloader::class,
    // ...
];

Define env variables:

PROFILER_ENABLE=true
PROFILER_ENDPOINT=http://127.0.0.1:8080/api/profiler/store
PROFILER_APP_NAME="My super app"
PROFILER_MIDDLEWARE_DEFAULT_ENABLED=true

Usage

There are two ways to use profiler:

• Profiler as a middleware
• Profiler as an interceptor

Profiler as an interceptor

Interceptor will be useful if you want to profile some specific part of your application which supports using interceptors.

• Controllers,
• GRPC,
• Queue jobs,
• TCP
• Events.

namespace App\Bootloader;

use App\Interceptor\CustomInterceptor;
use Spiral\Bootloader\DomainBootloader;
use Spiral\Core\CoreInterface;

class AppBootloader extends DomainBootloader
{
    protected const SINGLETONS = [
        CoreInterface::class => [self::class, 'domainCore']
    ];

    protected const INTERCEPTORS = [
        \Spiral\Profiler\ProfilerInterceptor::class
    ];
}

Read more about interceptors here.

Profiler as a middleware

To use profiler as a middleware you need to add it to your router.

Global middleware

namespace App\Bootloader;

use Spiral\Bootloader\Http\RoutesBootloader as BaseRoutesBootloader;
use Spiral\Profiler\ProfilerMiddleware;

final class RoutesBootloader extends BaseRoutesBootloader
{
    protected function globalMiddleware(): array
    {
        return [
            ProfilerMiddleware::class,  // <================
            LocaleSelector::class,
            ErrorHandlerMiddleware::class,
            JsonPayloadMiddleware::class,
            HttpCollector::class,
        ];
    }
    
    // ...
}

Route group middleware

namespace App\Bootloader;

use Spiral\Bootloader\Http\RoutesBootloader as BaseRoutesBootloader;
use Spiral\Profiler\ProfilerMiddleware;

final class RoutesBootloader extends BaseRoutesBootloader
{
    // ...

    protected function middlewareGroups(): array
    {
        return [
            'web' => [
                CookiesMiddleware::class,
                SessionMiddleware::class,
                CsrfMiddleware::class,
            ],
            'profiler' => [                  // <================
                ProfilerMiddleware::class,
                'middleware:web',
            ],
        ];
    }
    
    // ...
}

Route middleware

class HomeController implements SingletonInterface
{
    #[Route(route: '/', name: 'index.page', methods: ['GET'], middleware: 'profiler')]
    public function index(...): void 
    {
        // ...
    }
    
    #[Route(route: '/', name: 'index.page', methods: ['GET'], middleware: \Spiral\Profiler\ProfilerMiddleware::class)]
    public function index(...): void 
    {
        // ...
    }
}

Profiling strategy.

By default, middleware start profiling on every request. Н You can configure profiling to be enabled only for certain requests.

1. Set env variable PROFILER_MIDDLEWARE_DEFAULT_ENABLED to false.

PROFILER_MIDDLEWARE_DEFAULT_ENABLED=false

2. Pass Http header X-Spiral-Profiler-Enable=1 for request you want to profile.