README

A zero-dependency, single-class PHP profiler for measuring elapsed time and memory usage between named checkpoints.

Positioning

PerformanceMeter is intentionally minimal — a single final class with a handful of static methods that works without any other dependency. It exists to fill a specific niche:

Quick, single-file timing checks where pulling in a full profiling library would be overkill.

It is not a replacement for full-featured profilers; it is the cheapest possible thing that lets you answer "how long did this block take and how much memory did it use?".

When to use this

• One-off benchmarking scripts and microbenchmarks
• CLI tools and cron jobs where you want a quick elapsed-time print at the end
• Tutorial / educational code where introducing a heavier dependency would obscure the lesson
• Library examples and reproduction scripts in bug reports
• Hot-path probes during local development, when adding a composer require round-trip is friction

When NOT to use this

If you are reaching for any of the above, this package is not the right tool — and that is by design.

Requirements

• PHP 8.1 or higher
• No runtime dependencies

Installation

composer require initphp/performance-meter

You can also include src/PerformanceMeter.php (and src/Exception/PointerNotFoundException.php) manually if you cannot use Composer — the package has no transitive dependencies.

Quick start

require_once 'vendor/autoload.php';

use InitPHP\PerformanceMeter\PerformanceMeter;

PerformanceMeter::setPointer('main');

for ($i = 0; $i <= 1000; $i++) {
    usleep(10);
}

PerformanceMeter::setPointer('mainEnd');

echo PerformanceMeter::elapsedTime('main', 'mainEnd', 3) . ' seconds elapsed' . PHP_EOL;
echo PerformanceMeter::memoryUsage('main', 'mainEnd', 2) . ' memory used' . PHP_EOL;

// Example output:
// 0.015 seconds elapsed
// 0.77KB memory used

Open-ended measurement

When you only pass a starting checkpoint, the second argument defaults to "now":

PerformanceMeter::setPointer('boot');

// ... do work ...

echo PerformanceMeter::elapsedTime('boot') . ' seconds since boot' . PHP_EOL;

mark() alias

mark($name) is a one-to-one alias of setPointer($name) for readers who prefer stopwatch-style vocabulary:

PerformanceMeter::mark('before');
heavy_work();
PerformanceMeter::mark('after');

echo PerformanceMeter::elapsedTime('before', 'after');

More usage patterns — peak memory, comparing two implementations, resetting between runs — live in docs/cookbook.md.

API at a glance

elapsedTime() and memoryUsage() throw InitPHP\PerformanceMeter\Exception\PointerNotFoundException when $start (or a non-null $end) does not match a recorded checkpoint.

Full reference with parameter notes, error conditions and runnable examples: docs/api-reference.md.

Documentation

• docs/getting-started.md — install, first measurement, conceptual model
• docs/api-reference.md — every public method, parameter by parameter
• docs/cookbook.md — real-world recipes (CLI benchmarks, cron timing, A/B comparisons, peak memory tracking, v1 → v2 migration)

Migrating from v1.x to v2.0

v2.0 is a clean break that fixes real bugs and tightens the API. Most callers only need to upgrade PHP.

A migration cookbook entry with side-by-side diffs lives in docs/cookbook.md.

Contributing

This package follows the org-wide InitPHP contribution guide — PSR-12, declare(strict_types=1);, PHPStan at the configured level, PHPUnit-tested behaviour changes, Conventional Commits.

Locally:

composer install
composer test         # PHPUnit
composer phpstan      # static analysis
composer cs-check     # coding standards (use cs-fix to apply)
composer qa           # all of the above

CI runs on PHP 8.1 → 8.4 against both highest and lowest installable dependencies.

Security

Please report security issues privately — see the org-wide SECURITY.md. Do not open public issues for vulnerabilities.

Credits

• Muhammet ŞAFAK — <info@muhammetsafak.com.tr>

License

Released under the MIT License. Copyright © 2022-2026 InitPHP.