README

MicroBench is a simple PHP tool for micro-benchmarking your code developed by Serhii Korniushov. It measures execution time, memory usage, and memory peak usage. It supports high-resolution time (hrtime) on PHP 7.3+.

Features

• Measures elapsed time (microtime and hrtime).
• Tracks memory usage and peak memory usage.
• Simple API: start(), finish(), getReport().
• Easy to install with Composer.
• Provides human-readable time formatting.

Installation

Install MicroBench using Composer:

composer require --dev serhiikorniushov/micro-bench

This command will download the MicroBench library and its dependencies into your project's vendor directory.

Usage

Here's a basic example of how to use MicroBench:

<?php
require_once __DIR__ . '/vendor/autoload.php'; // Include Composer's autoloader
use SerhiiKorniushov\MicroBench\MicroBench;
// Start the benchmark
$benchmark = (new SerhiiKorniushov\MicroBench\MicroBench)->start();
// Code to benchmark
for ($i = 0; $i < 100000; $i++) {
// Some operation
$a = $i * 2;
}
// Get elapsed microtime time in human-readable format
$benchmark->finish()->getElapsedMicroTimeReadable();
// OR
// Finish the benchmark
$benchmark->finish();
// Get the report
$report = $benchmark->getReport();
// Output the results
echo "Elapsed time: " . $benchmark->getElapsedMicroTimeReadable() . "\n";
echo "Elapsed time (seconds): " . $report['elapsed']['microtime'] . " s\n";
echo "Memory usage: " . $report['elapsed']['memory_usage'] . " bytes\n";
echo "Memory peak usage: " . $report['elapsed']['memory_peak_usage'] . " bytes\n";
// Print the full report (optional)
// print_r($report);
?>

Explanation:

1. Include Autoloader: require_once __DIR__ . '/vendor/autoload.php'; loads the Composer-generated autoloader, making the MicroBench class available.
2. Create Instance: $bench = new MicroBench(); creates a new MicroBench object.
3. Start Benchmark: $bench->start(); starts the timer and records initial memory usage. It throws a RuntimeException if called when a benchmark is already running or has finished.
4. Code to Benchmark: This is the section where you place the code you want to test.
5. Finish Benchmark: $bench->finish(); stops the timer and records final memory usage. It throws a RuntimeException if called before start() or if called a second time.
6. Get Report: $report = $bench->getReport(); retrieves a detailed report as an associative array.
7. Output Results: The example shows how to access specific values from the report, such as elapsed time and memory usage. getElapsedMicroTimeReadable() provides a nicely formatted time string.

API Reference

• start(): Starts the benchmark.
• finish(): Finishes the benchmark.
• getReport(): Returns a detailed report array.
• isStarted(): Checks if the benchmark has been started.
• isFinished(): Checks if the benchmark has been finished.
• getElapsedMicroTime(): Returns the elapsed time in seconds (float).
• getElapsedMicroTimeReadable(): Returns the elapsed time in a human-readable format (e.g., "100 ms", "1 s").
• formatMicroTimeDiff(float $timeDiff): (Static) Formats a time difference (in seconds) into a human-readable string.
• getStartMicroTime(): Returns the starting microtime.
• getStartMemoryUsage(): Returns the starting memory usage.
• getStartMemoryUsageReal(): Returns the starting real memory usage.
• getFinishMicroTime(): Returns the finishing microtime.
• getFinishMemoryUsage(): Returns the finishing memory usage.
• getFinishMemoryUsageReal(): Returns the finishing real memory usage.
• getStartMemoryPeakUsage(): Returns the starting memory peak usage.
• getStartMemoryPeakUsageReal(): Returns the starting real memory peak usage.
• getFinishMemoryPeakUsage(): Returns the finishing memory peak usage.
• getFinishMemoryPeakUsageReal(): Returns the finishing real memory peak usage.
• getStartHrTime(): Returns the starting hrtime (PHP 7.3+).
• getFinishHrTime(): Returns the finishing hrtime (PHP 7.3+).