README

BENCHMARK
^{PHP PERFORMANCE INSIGHTS}

Benchmark is a high-performance PHP library for measuring execution time and memory usage of code. Designed with precision, fault tolerance, and extensibility in mind, it provides advanced features like middleware hooks, configurable options, and detailed reporting to help developers optimize their applications.

Key Features

• High-Resolution Timing: Nanosecond-level precision using hrtime.
• Memory Tracking: Track memory usage and peak memory consumption.
• Middleware Support: Pre- and post-processing hooks for advanced customization.
• Grouped Benchmarking: Run and analyze multiple benchmarks simultaneously.
• Statistical Analysis: Generate averages, variances, and detailed reports over multiple iterations.
• Configurable Options: Toggle features like verbose output and peak memory tracking.
• Integration Ready: Export reports in JSON, array, or human-readable formats.
• Lightweight and Efficient: Minimal overhead to keep performance at its peak.

Installation

Install via composer:

composer "require jamesgober/benchmark"

Usage

Basic Benchmark

use JG\Benchmark\Benchmark;

$benchmark = new Benchmark();

$benchmark->start('example');
// Code to benchmark
usleep(1000); // Simulate a short delay
$benchmark->stop('example');

// Get results
echo $benchmark->getTime('example'); // Outputs elapsed time
echo $benchmark->getMemory('example'); // Outputs memory usage

Grouped Benchmark Report

$benchmark->start('task1');
usleep(2000);
$benchmark->stop('task1');

$benchmark->start('task2');
usleep(1000);
$benchmark->stop('task2');

print_r($benchmark->getReport());

Example Output

Array
(
    [task1] => Array
        (
            [time] => 0.002 ms
            [memory] => 1.23 KB
            [peak_memory] => 1.45 KB
        )

    [task2] => Array
        (
            [time] => 0.001 ms
            [memory] => 1.12 KB
            [peak_memory] => 1.32 KB
        )
)

Middleware Example

$benchmark->addMiddleware('before', function ($name, $data) {
    echo "Starting benchmark: $name\n";
});

$benchmark->addMiddleware('after', function ($name, $data) {
    echo "Finished benchmark: $name\n";
});

$benchmark->start('middleware_example');
usleep(1500);
$benchmark->stop('middleware_example');

Configuration

Customize behavior by passing an array of options to the constructor:

$config = [
    'track_peak_memory' => true,
    'verbose' => false,
];

$benchmark = new Benchmark($config);

Testing

Run PHPUnit tests:

composer test

Run static analysis with PHPStan:

composer phpstan

Run both tests and static analysis:

composer check

Reporting Bugs and Feature Requests

For bugs, feature requests, or security issues, please visit our Issue Tracker.

If you discover a vulnerability, refer to our Security Policy.

Contributing

Contributions are welcome! Please follow our Contribution Guidelines:

1. Fork the repository.
2. Create a feature branch.
3. Commit your changes with descriptive messages.
4. Open a pull request.

Ensure all tests pass and adhere to the project's coding standards.

License

This library is licensed under the Apache-2.0 License.