sleep
Pauses execution of the current script for the given whole number of seconds.
sleep(int $seconds): int- Added in PHP 4.0
Parameters
| Parameter | Type | Description |
|---|---|---|
$seconds | int | How long to halt, in whole seconds. Must be zero or greater. |
Return value
int0 on success. If interrupted by a signal it returns a non-zero value: the number of seconds left to sleep on POSIX systems, and always 192 (WAIT_IO_COMPLETION) on Windows.
Errors
Throws a ValueError if seconds is negative.
Changelog
- PHP 8.0.0A negative seconds value now throws a ValueError; previously it raised E_WARNING and returned false.
sleep() blocks the current PHP process for a whole number of seconds. Nothing else in that process runs meanwhile — no output is flushed, no other request is served by that worker.
When to reach for it
- Backing off between retries when an API returns 429 or a connection fails.
- Pacing a CLI worker or import loop so you do not saturate a database.
- Waiting for an external resource in a script you run yourself, not in a web request.
What trips people up
Only whole seconds. sleep(0.5) is not half a second — under strict_types=1 it is a TypeError, and otherwise the float is deprecated-cast toward 0. Use usleep(500000) or time_nanosleep() for sub-second delays.
On a web server, sleeping ties up a PHP-FPM worker for the whole duration; a handful of sleeping requests can exhaust the pool. Move waits to a queue worker instead. Sleep time does not count toward max_execution_time on Unix (it does on Windows), so a sleeping script can outlive the limit you thought you set. Finally, always check the return value in signal-handling code: a non-zero result means the sleep was cut short.
Example
When to use it
- Waiting a few seconds between retries when a remote API rate-limits you.
- Slowing a bulk import loop so replication or a rate-limited endpoint can keep up.
- Giving a just-started background service a moment before a health check in a deploy script.
Frequently asked questions
How do I sleep for less than a second in PHP?
Use usleep(), which takes microseconds, or time_nanosleep() for nanosecond precision. sleep() only accepts whole seconds.
Does sleep count toward max_execution_time?
Not on Unix-like systems, where only CPU time is counted, but it does on Windows. Do not rely on max_execution_time to cap a script that sleeps.
Why does sleep return a non-zero number?
The pause was interrupted by a signal. On POSIX the value is the number of seconds still left to sleep; on Windows it is always 192.
More examples
Exponential backoff on retries
The loop prints two failures with waits of 1 and 2 seconds before succeeding on the third attempt, the standard doubling backoff pattern.
<?php
$attempt = 0;
while (++$attempt <= 3) {
$ok = $attempt === 3;
echo "attempt $attempt: ", $ok ? "success\n" : "failed\n";
if ($ok) break;
$wait = 2 ** ($attempt - 1);
echo " waiting {$wait}s\n";
sleep($wait);
}Negative input throws
PHP 8 turns a negative argument into a ValueError instead of a warning, while sleep(0) returns int(0) immediately without pausing.
<?php
try {
sleep(-1);
} catch (ValueError $e) {
echo get_class($e), ': ', $e->getMessage(), "\n";
}
var_dump(sleep(0));
Discussion