sleep()

La función sleep() de PHP pausa la ejecución del script durante un número fijo de segundos enteros. Este artículo explica su sintaxis y valores de retorno, cuándo es realmente útil retrasar un script, los problemas relacionados con el bloqueo y las señales, y cómo sleep() se compara con sus variantes de sub-segundo.

Sintaxis

sleep(int $seconds): int|false

• $seconds — el número de segundos enteros para detener el script. Debe ser un entero no negativo; pasar un valor negativo genera un error.
• Valor de retorno — sleep() devuelve 0 en caso de éxito. Si la llamada es interrumpida por una señal (por ejemplo, una alarma o un controlador Ctrl+C en la CLI), devuelve el número de segundos que quedaban por dormir, que es un entero positivo distinto de cero. Devuelve false solo si la llamada falla por completo.

Dado que sleep() solo acepta enteros, el retraso mínimo que puede producir es de un segundo. Para un control más preciso, usa usleep() (microsegundos) o time_nanosleep() (nanosegundos).

Uso básico

Llama a sleep() y pasa el número de segundos que deseas esperar. Todo lo que viene después de la llamada se ejecuta solo cuando ha transcurrido el retraso:

El script imprime el primer mensaje, se bloquea durante cinco segundos y luego imprime el segundo. Puedes ver la pausa claramente midiendo el tiempo del script:

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

Esto imprime Waited about 2 seconds, confirmando la pausa. (Consulta microtime() para medir el tiempo transcurrido.)

¿Cuándo usarías sleep()?

sleep() es más útil en scripts de línea de comandos y en segundo plano donde una pausa breve es intencional:

• Sondeo con retraso — verificar una cola, un archivo o una API en un intervalo regular en lugar de en un bucle ajustado que consume mucha CPU.
• Limitación de velocidad / ser un buen ciudadano de API — espaciar las solicitudes para no superar el límite de velocidad de un tercero.
• Espera antes de reintentar — esperar antes de reintentar una operación fallida, a menudo con un retraso creciente.

Aquí tienes un patrón simple de reintento con espera progresiva:

<?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
}
?>

Esto imprime dos mensajes de "failed" (esperando 1s y luego 2s) y finalmente Succeeded on attempt 3.

sleep() bloquea todo el proceso

sleep() es una llamada bloqueante: nada más ocurre en ese proceso PHP mientras espera. Esto importa de dos maneras:

• Nunca llames a sleep() en una solicitud web normal. Una solicitud en estado de espera mantiene ocupado un trabajador PHP-FPM (y a menudo una conexión del navegador) sin hacer nada, lo que perjudica el rendimiento y puede activar los límites de tiempo de espera de las solicitudes. Las pausas pertenecen a scripts CLI, trabajos cron y trabajadores de cola.
• No cede el control a otro código. Si necesitas esperar sin bloquear, eso es tarea para un bucle de eventos o un entorno de ejecución asíncrono, no para sleep().

Manejo de interrupciones durante la espera

En la CLI, una señal puede acortar una espera. Cuando eso sucede, sleep() devuelve los segundos restantes en lugar de 0, para que puedas reanudar la espera si lo deseas:

<?php
$remaining = sleep(5);

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

Cuando la espera termina normalmente, $remaining es 0 y el script imprime Slept the full duration.

Retrasos de sub-segundo: usleep() y similares

Dado que sleep() solo acepta segundos enteros, PHP ofrece alternativas más precisas:

Por ejemplo, para limitar un bucle a aproximadamente 10 iteraciones por segundo, haz una pausa de 100,000 microsegundos (una décima de segundo) en cada pasada:

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

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

Esto imprime Tick 1, Tick 2, Tick 3 con aproximadamente una décima de segundo entre cada línea.

Conclusión

sleep() es una forma confiable de pausar un script PHP durante un número entero de segundos. Recuerda que bloquea todo el proceso, así que mantenla fuera de las solicitudes web en vivo y resérvala para herramientas CLI, trabajos cron y trabajadores — típicamente para sondeo, limitación de velocidad y espera antes de reintentar. Cuando necesites una temporización más precisa, recurre a usleep(), time_nanosleep() o time_sleep_until(). Para más información sobre cómo trabajar con el tiempo en PHP, consulta Fecha y hora en PHP.

Práctica