Logo
SOURCE CODE Documentation

Stackwatch

A minimalist multi-metric PHP Profiler.

composer require bakame/stackwatch:^0.13.0
Love this package ? Sponsor its development
!

Once a new major version is released, the previous stable release remains supported for six more months with patches and security fixes.

Introduction

Stackwatch is a lightweight profiler for PHP 8.1+. It helps you measure performance with precision—without unnecessary complexity.

Once installed, it will allow you to

Profile any block using closures

use Bakame\Stackwatch\Profiler;

$duration = Profiler::metrics(function () {
    // code that will be profiled
})->executionTime;
// $duration is the execution time in nanosecond using hrtime instead of microtime

Segment code with named checkpoints

use Bakame\Stackwatch\Timeline;

$timeline = Timeline::start('start');
// the piece of code to be profiled
$timeline->capture('middle');
// another piece of code
$duration = $timeline->take('end')->metrics->executionTime;
// $duration is expressed in nanoseconds

Use a CLI command to profile your codebase

Let’s say you have the following file /path/to/profiling/code.php:

<?php

declare(strict_types=1);

namespace Foobar\Baz;

use Bakame\Stackwatch\Profile;

use function random_int;
use function usleep;

require 'vendor/autoload.php';

trait TimerTrait {
    #[Profile]
    private function test() : int {
        usleep(100);

        return random_int(1, 100);
    }
}

enum MyEnum
{
    use TimerTrait;

    case Case1;
    case Case2;
}

If you mark your code with the Bakame\Stackwatch\Profile attribute and run the CLI command:

php vendor/bin/stackwatch --path=/path/to/profiling/code.php

It will output the following with no complex setup.

stackwatch v0.13.0 (Marrakesh) by Ignace Nyamagana Butera and contributors.

Runtime: PHP 8.3.24 OS: Linux Memory Limit: 64M

(Average) Target: Foobar\Baz\Foobar::test; Path: /path/to/profiling/code.php; Iterations: 3; Warmup: 0;

CPU Time ............................................................. 19.000 µs
Execution Time ...................................................... 144.611 µs
Memory Usage ............................................................ 1.0 KB
Real Memory Usage ........................................................ 0.0 B
Peak Memory Usage ........................................................ 0.0 B
Real Peak Memory Usage ................................................... 0.0 B

Motivation

Stackwatch bridges the gap between basic timers and heavy profiling tools like PHPBench, Xdebug or Blackfire. It is perfect for:

  • Isolated performance testing
  • Annotated profiling of large codebases
  • Lightweight integration into dev workflows
Logo