sleep()

A função sleep() do PHP pausa a execução do seu script por um número fixo de segundos inteiros. Este artigo explica a sua sintaxe e valores de retorno, quando atrasar um script é realmente útil, os cuidados em relação ao bloqueio e sinais, e como sleep() se compara às suas variantes de sub-segundo.

Sintaxe

sleep(int $seconds): int|false

• $seconds — o número de segundos inteiros para interromper o script. Deve ser um inteiro não negativo; passar um valor negativo aciona um erro.
• Valor de retorno — sleep() retorna 0 em caso de sucesso. Se a chamada for interrompida por um sinal (por exemplo, um alarme ou um manipulador Ctrl+C na CLI), ela retorna o número de segundos restantes para dormir, que é um inteiro positivo diferente de zero. Retorna false apenas se a chamada falhar completamente.

Como sleep() aceita apenas inteiros, o menor atraso que pode produzir é de um segundo. Para um controle mais preciso, use usleep() (microssegundos) ou time_nanosleep() (nanossegundos).

Uso básico

Chame sleep() e passe o número de segundos que deseja aguardar. Tudo após a chamada só é executado depois que o atraso decorrer:

O script imprime a primeira mensagem, bloqueia por cinco segundos e, em seguida, imprime a segunda. Você pode ver a pausa claramente cronometrando o script:

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

Isso gera Waited about 2 seconds, confirmando a pausa. (Veja microtime() para medir o tempo decorrido.)

Quando usar sleep()?

sleep() é mais útil em scripts de linha de comando e em segundo plano, onde uma breve pausa é intencional:

• Polling com atraso — verificar uma fila, um arquivo ou uma API em intervalos regulares, em vez de em um laço apertado e que consome muito CPU.
• Limitação de taxa / ser um bom cidadão de API — espaçar as requisições para não exceder o limite de taxa de terceiros.
• Back-off em nova tentativa — aguardar antes de tentar novamente uma operação com falha, geralmente com um atraso crescente.

Aqui está um padrão simples de nova tentativa com back-off:

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

Isso imprime duas mensagens de "falha" (aguardando 1s e depois 2s) e finalmente Succeeded on attempt 3.

sleep() bloqueia todo o processo

sleep() é uma chamada bloqueante: nada mais acontece nesse processo PHP enquanto ele aguarda. Isso importa de duas formas:

• Nunca chame sleep() em uma requisição web normal. Uma requisição em espera mantém um worker do PHP-FPM (e frequentemente uma conexão do navegador) ocupada sem fazer nada, o que prejudica o throughput e pode acionar limites de tempo limite de requisição. As pausas pertencem a scripts CLI, cron jobs e workers de fila.
• Não cede a outro código. Se você precisa aguardar sem bloquear, isso é trabalho para um loop de eventos ou runtime assíncrono, não para sleep().

Lidando com sleeps interrompidos

Na CLI, um sinal pode encerrar um sleep antecipadamente. Quando isso acontece, sleep() retorna os segundos restantes em vez de 0, para que você possa retomar a espera se desejar:

<?php
$remaining = sleep(5);

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

Quando o sleep termina normalmente, $remaining é 0 e o script imprime Slept the full duration.

Atrasos de sub-segundo: usleep() e outros

Como sleep() aceita apenas segundos inteiros, o PHP oferece alternativas mais precisas:

Por exemplo, para limitar um laço a aproximadamente 10 iterações por segundo, pause por 100.000 microssegundos (um décimo de segundo) em cada passagem:

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

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

Isso imprime Tick 1, Tick 2, Tick 3 com cerca de um décimo de segundo entre cada linha.

Conclusão

sleep() é uma maneira confiável de pausar um script PHP por um número inteiro de segundos. Lembre-se de que ele bloqueia o processo inteiro, portanto, mantenha-o fora de requisições web ao vivo e reserve-o para ferramentas CLI, cron jobs e workers — tipicamente para polling, limitação de taxa e back-off em novas tentativas. Quando precisar de temporização mais fina, use usleep(), time_nanosleep() ou time_sleep_until(). Para saber mais sobre como trabalhar com tempo no PHP, consulte PHP Date and Time.

Prática