https://github.com/cspray/precision-stopwatch
A library to precisely time PHP scripts, down to the nanosecond, using hrtime()
https://github.com/cspray/precision-stopwatch
Last synced: 8 months ago
JSON representation
A library to precisely time PHP scripts, down to the nanosecond, using hrtime()
- Host: GitHub
- URL: https://github.com/cspray/precision-stopwatch
- Owner: cspray
- License: mit
- Created: 2023-05-07T17:27:17.000Z (about 3 years ago)
- Default Branch: main
- Last Pushed: 2023-05-13T18:37:28.000Z (about 3 years ago)
- Last Synced: 2025-10-11T00:29:38.538Z (8 months ago)
- Language: PHP
- Size: 13.7 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Precision Stopwatch
Precisely time PHP scripts and code, down to the nanosecond, by utilizing the [hrtime](https://php.net/hrtime) function.
## Installing
[Composer](https://getcomposer.org) is the only supported method for installing this library.
```shell
composer require cspray/precision-stopwatch
```
## Usage Guide
Using the provided functionality involves the following steps:
1. Create a new instance of `Cspray\PrecisionStopwatch\Stopwatch`
2. Call `Stopwatch::start()`
3. Do the thing that you're timing!
4. Call `Stopwatch::mark()` (optional, see [_Marking Time_](#marking-time))
5. Call `Stopwatch::stop()`
6. Retrieve information about how long the Stopwatch ran with `Cspray\PrecisionStopwatch\Metrics`
The code examples below can be executed by cloning this repo and running the scripts available in `./examples`.
### Basic Usage
```php
start();
sleep(3);
$metrics = $stopwatch->stop();
echo 'Duration (ns): ', $metrics->getTotalDuration()->timeTakenInNanoseconds(), PHP_EOL;
echo 'Duration (ms): ', $metrics->getTotalDuration()->timeTakenInMilliseconds(), PHP_EOL;
```
If you execute this example you should see output similar to the following:
```text
% > php ./examples/usage-without-marks.php
Total time taken (ns): 1000584755
Total time taken (ms): 1000.584755
```
### Marking Time
Marking time allows you to retrieve the duration that a Stopwatch has ran to a certain point, while allowing the Stopwatch to continue running. Calling `Stopwatch::mark()` will return a `Cspray\PrecisionStopwatch\Marker` instance. In addition to retrieving the duration up to a certain point, available on the `Marker` instance, you can retrieve the duration between markers with the `Metrics` returned from `Stopwatch::stop()`.
```php
start();
usleep($sleepTime);
$mark1 = $stopwatch->mark();
usleep($sleepTime);
$mark2 = $stopwatch->mark();
usleep($sleepTime);
$mark3 = $stopwatch->mark();
usleep($sleepTime);
$metrics = $stopwatch->stop();
echo 'Total time taken (ns): ', $metrics->getTotalDuration()->timeTakenInNanoseconds(), PHP_EOL;
echo 'Total time taken (ms): ', $metrics->getTotalDuration()->timeTakenInMilliseconds(), PHP_EOL;
echo PHP_EOL;
$between1And3 = $metrics->getDurationBetweenMarkers($mark1, $mark3);
echo 'Time take between 1st and 3rd mark (ns): ', $between1And3->timeTakenInNanoseconds(), PHP_EOL;
echo 'Time take between 1st and 3rd mark (ms): ', $between1And3->timeTakenInMilliseconds(), PHP_EOL;
echo PHP_EOL;
echo 'Time taken up to 3rd mark (ns): ', $mark3->getDuration()->timeTakenInNanoseconds(), PHP_EOL;
echo 'Time taken up to 3rd mark (ms): ' , $mark3->getDuration()->timeTakenInMilliseconds(), PHP_EOL;
```
If you execute this example you should see output similar to the following:
```text
% > php ./examples/usage-without-marks.php
Total time taken (ns): 3000608258
Total time taken (ms): 3000.608258
Time take between 1st and 3rd mark (ns): 1500407710
Time take between 1st and 3rd mark (ms): 1500.40771
Time taken up to 3rd mark (ns): 2250497069
Time taken up to 3rd mark (ms): 2250.497069
```