README

Precise code execution timer with lap tracking and memory measurement.

Requirements

Dependency	Version
PHP	^8.2

No external dependencies required.

Installation

composer require philiprehberger/php-stopwatch

Usage

Quick measurement

use PhilipRehberger\Stopwatch\Stopwatch;

$result = Stopwatch::measure(function () {
    // Code to measure
    file_get_contents('https://example.com');
});

echo $result->durationFormatted; // "123.45ms"
echo $result->memoryFormatted;   // "1.50KB"

Measurement with return value

$outcome = Stopwatch::measureWithResult(function () {
    return User::query()->where('active', true)->get();
});

$users = $outcome['result'];
echo $outcome['measure']->durationFormatted; // "45.12ms"

Manual start/stop with laps

$sw = Stopwatch::start('data-pipeline');

// Phase 1
$data = loadData();
$sw->lap('load');

// Phase 2
$transformed = transform($data);
$sw->lap('transform');

// Phase 3
save($transformed);
$sw->lap('save');

$result = $sw->stop();

echo $result->report();
// Stopwatch [data-pipeline]
// -------------------------
// Duration: 1.23s
// Memory:   3.25MB
// Peak:     5.10MB
//
// Laps:
//   load — 200.00ms (cumulative: 200.00ms)
//   transform — 800.00ms (cumulative: 1000.00ms)
//   save — 230.00ms (cumulative: 1230.00ms)

Check elapsed time while running

$sw = Stopwatch::start();

doSomeWork();

if ($sw->elapsed() > 5000) {
    // Already over 5 seconds, skip remaining work
}

$result = $sw->stop();

API

Method	Returns	Description
`Stopwatch::start(?string $name)`	`RunningStopwatch`	Start a new stopwatch with an optional name
`Stopwatch::measure(callable $fn)`	`MeasureResult`	Measure execution time and memory of a callable
`Stopwatch::measureWithResult(callable $fn)`	`array{result, measure}`	Measure while preserving the return value
`RunningStopwatch->lap(?string $name)`	`self`	Record a lap with an optional name
`RunningStopwatch->stop()`	`StopwatchResult`	Stop the timer and return results
`RunningStopwatch->elapsed()`	`float`	Get elapsed milliseconds while still running
`RunningStopwatch->isRunning()`	`bool`	Check if the stopwatch is still active
`StopwatchResult->report()`	`string`	Generate a formatted report with all laps

Value Objects

StopwatchResult — duration (float, ms), durationFormatted (string), memory (int, bytes), memoryFormatted (string), peakMemory (int, bytes), laps (array), name (?string)

MeasureResult — duration (float, ms), durationFormatted (string), memory (int, bytes), memoryFormatted (string)

Lap — name (?string), duration (float, ms), cumulativeDuration (float, ms)

Development

composer install
vendor/bin/phpunit
vendor/bin/pint --test
vendor/bin/phpstan analyse

License

MIT

philiprehberger / php-stopwatch

Maintainers

Package info

Statistics

Security