sleep()

The PHP sleep() function pauses the execution of your script for a fixed number of whole seconds. This article explains its syntax and return values, when delaying a script is actually useful, the gotchas around blocking and signals, and how sleep() compares to its sub-second cousins.

Syntax

sleep(int $seconds): int|false

• $seconds — the number of whole seconds to halt the script. It must be a non-negative integer; passing a negative value triggers an error.
• Return value — sleep() returns 0 on success. If the call is interrupted by a signal (for example, an alarm or a Ctrl+C handler on the CLI), it returns the number of seconds left to sleep, which is a non-zero positive integer. It returns false only if the call fails outright.

Because sleep() only accepts integers, the shortest delay it can produce is one second. For finer control, use usleep() (microseconds) or time_nanosleep() (nanoseconds).

Basic usage

Call sleep() and pass the number of seconds you want to wait. Everything after the call runs only once the delay has elapsed:

The script prints the first message, blocks for five seconds, then prints the second. You can see the gap clearly by timing the script:

<?php
$start = microtime(true);
sleep(2);
$elapsed = microtime(true) - $start;
echo "Waited about " . round($elapsed, 1) . " seconds\n";
?>

This outputs Waited about 2 seconds, confirming the pause. (See microtime() for measuring elapsed time.)

When would you use sleep()?

sleep() is most useful in command-line and background scripts where a short pause is intentional:

• Polling with a delay — checking a queue, a file, or an API on a regular interval instead of in a tight, CPU-hungry loop.
• Rate limiting / being a good API citizen — spacing out requests so you do not exceed a third-party rate limit.
• Retry back-off — waiting before retrying a failed operation, often with an increasing delay.

Here is a simple retry-with-back-off pattern:

<?php
$maxRetries = 3;

for ($attempt = 1; $attempt <= $maxRetries; $attempt++) {
    $ok = ($attempt === 3); // pretend it succeeds on the 3rd try
    if ($ok) {
        echo "Succeeded on attempt $attempt\n";
        break;
    }
    echo "Attempt $attempt failed, retrying...\n";
    sleep($attempt); // back off longer each time: 1s, then 2s
}
?>

This prints two "failed" messages (waiting 1s then 2s) and finally Succeeded on attempt 3.

sleep() blocks the whole process

sleep() is a blocking call: nothing else happens in that PHP process while it waits. This matters in two ways:

• Never call sleep() in a normal web request. A sleeping request keeps a PHP-FPM worker (and often a browser connection) tied up doing nothing, which hurts throughput and can trip request-timeout limits. Pauses belong in CLI scripts, cron jobs, and queue workers.
• It does not yield to other code. If you need to wait without blocking, that is a job for an event loop or async runtime, not sleep().

Handling interrupted sleeps

On the CLI, a signal can cut a sleep short. When that happens, sleep() returns the seconds still remaining instead of 0, so you can resume the wait if you want:

<?php
$remaining = sleep(5);

if ($remaining > 0) {
    echo "Interrupted with $remaining seconds left\n";
} else {
    echo "Slept the full duration\n";
}
?>

When the sleep finishes normally, $remaining is 0 and the script prints Slept the full duration.

Sub-second delays: usleep() and friends

Because sleep() only takes whole seconds, PHP offers more precise alternatives:

For example, to throttle a loop to roughly 10 iterations per second, pause for 100,000 microseconds (a tenth of a second) on each pass:

<?php
$interval = 1000000 / 10; // microseconds per iteration -> 100000

for ($i = 1; $i <= 3; $i++) {
    echo "Tick $i\n";
    usleep((int) $interval);
}
?>

This prints Tick 1, Tick 2, Tick 3 with about a tenth of a second between each line.

Conclusion

sleep() is a reliable way to pause a PHP script for a whole number of seconds. Remember that it blocks the entire process, so keep it out of live web requests and reserve it for CLI tools, cron jobs, and workers — typically for polling, rate limiting, and retry back-off. When you need finer timing, reach for usleep(), time_nanosleep(), or time_sleep_until(). For more on working with time in PHP, see PHP Date and Time.

Practice