hrtime()

This article covers the PHP hrtime() function: what it does, how its two return modes differ, why its monotonic clock makes it the right tool for benchmarking, and worked examples you can run.

Introduction to the hrtime() function

hrtime() is a built-in function available in PHP 7.3 and later. It reads the system's high-resolution timer and returns the current time with nanosecond precision. Its main purpose is benchmarking — measuring how long a piece of code takes to run.

The key word is monotonic. A monotonic clock only ever moves forward at a steady rate; it is not affected by system clock changes, NTP adjustments, or daylight-saving transitions. That is exactly what you want for measuring elapsed time. Wall-clock functions like microtime() and time() can jump backward or forward if the system clock is corrected mid-measurement, which would corrupt a benchmark.

Note that hrtime() measures time since an arbitrary epoch (often system boot). The absolute value is meaningless on its own — it is only useful as a difference between two readings.

Syntax and return values

hrtime(bool $as_number = false): array|int|false

• $as_number — when false (default), returns a two-element array [seconds, nanoseconds]. When true, returns a single integer: the total time in nanoseconds.
• Returns false if the high-resolution timer is unavailable.

The single-integer form (hrtime(true)) is the most convenient for benchmarking because you can subtract two readings directly.

Benchmarking with hrtime(true)

The logic is: capture $start, run the code, capture $end, then take the difference. Because the readings are in nanoseconds, divide by 1e6 (1,000,000) to get milliseconds, or by 1e9 to get seconds. The result for a 1.5 ms sleep will be roughly 1.5 ms (the exact value varies slightly with system overhead).

Reading the [seconds, nanoseconds] array

Called without an argument, hrtime() returns an array you can destructure:

<?php
[$seconds, $nanoseconds] = hrtime();

echo "Seconds since epoch:     $seconds\n";
echo "Nanoseconds component:   $nanoseconds\n";

// Combine both parts into total nanoseconds yourself
$totalNs = $seconds * 1e9 + $nanoseconds;
echo "Total nanoseconds:       $totalNs\n";
?>

This form is rarely needed in practice — hrtime(true) already gives you the combined value — but it shows what the timer is really reporting.

When to use hrtime() vs microtime()

• Use hrtime() for micro-benchmarks and any measurement where accuracy matters. It is monotonic and offers nanosecond resolution.
• Use microtime() when you need a wall-clock timestamp (seconds since the Unix epoch) rather than an elapsed duration.

Gotchas

• Precision of float math. Dividing nanoseconds by 1e6 produces a float, which is fine for display but can lose precision over very long intervals. Keep the difference in integer nanoseconds while measuring, and only convert at the end.
• Very long-running scripts. On a 32-bit build, the nanosecond integer can overflow. For arbitrarily large differences, use the bcmath or gmp extensions for precise arithmetic.
• Don't treat the value as a date. It is not a Unix timestamp; you cannot format it with date().

Conclusion

hrtime() is the right tool for measuring how long PHP code takes to run. Use hrtime(true) to grab a nanosecond reading before and after the code, subtract, and convert to your preferred unit. Its monotonic clock makes the result reliable even when the system clock changes — something microtime() cannot guarantee.

Practice