time_sleep_until()

The PHP time_sleep_until() function pauses a script until an absolute point in time, expressed as a Unix timestamp. Unlike sleep(), which waits for a duration ("sleep 10 seconds"), this function waits until a moment ("sleep until 14:30:00"). This article explains its syntax, return value, edge cases, and when to reach for it.

Syntax

time_sleep_until(float $timestamp): bool

• $timestamp — the Unix timestamp (seconds since the epoch) the script should resume at. Because the parameter is a float, you can pass fractional seconds for sub-second precision (e.g. time() + 2.5).
• Return value — returns true on success and false on failure.

If the supplied timestamp is already in the past, the function returns immediately without sleeping. In PHP 8 it returns false and emits a warning; in PHP 7 it also returned false. Either way, your script does not block — so don't rely on the call to "wait" when the target time has elapsed.

How to use the time_sleep_until() function

Call the function and pass the timestamp at which the script should resume. The most common pattern is to add an offset to the current time returned by time():

Here time() + 10 is an absolute Unix timestamp ten seconds in the future. time_sleep_until() blocks until the system clock reaches that value, then execution continues and prints the final message.

Waiting for the next whole minute

Because you pass an absolute time, time_sleep_until() is ideal for aligning work to a clock boundary — for example, running a task exactly when the next minute begins:

<?php
$now  = time();
$next = $now - ($now % 60) + 60; // round up to the next whole minute
echo "Now: " . date('H:i:s', $now) . "\n";
time_sleep_until($next);
echo "Resumed at: " . date('H:i:s', $next) . "\n";
?>

The expression $now - ($now % 60) + 60 strips the seconds from the current timestamp and adds 60, giving the timestamp of the upcoming minute. This is more accurate than sleep(60), which would drift if the script started partway through a minute.

Sub-second precision

Passing a fractional timestamp delays for a fraction of a second:

<?php
$start = microtime(true);
time_sleep_until(microtime(true) + 0.25); // wait 250 ms
echo "Waited " . round(microtime(true) - $start, 2) . " seconds\n";
?>

For pausing by a duration rather than until an absolute moment, prefer usleep() (microseconds) or time_nanosleep() (nanoseconds).

time_sleep_until() vs sleep()

Choose time_sleep_until() when you know the exact clock time you want to resume at; choose sleep()/usleep() when you only care how long to pause. You can build the target timestamp from helpers like time() or microtime().

Performance considerations

time_sleep_until() blocks the current process until the target time is reached. It uses minimal CPU while waiting, but a blocked process is still a stalled one: in a web request, a long sleep can hit the max_execution_time limit or the web server's request timeout and produce a 504 error. It is therefore best suited to CLI scripts, cron jobs, and worker processes rather than user-facing requests. Avoid calling it in performance-critical paths, and keep the wait short in any HTTP context.

Conclusion

time_sleep_until() pauses a script until an absolute Unix timestamp, making it the right tool for clock-aligned delays where sleep() would only let you specify a duration. Remember that it returns true/false, never blocks for a past timestamp, accepts fractional seconds, and ties up the whole process while it waits — so reserve it for CLI and worker code rather than web requests.

Practice