time_sleep_until()

A função PHP time_sleep_until() pausa um script até um ponto absoluto no tempo, expresso como um timestamp Unix. Ao contrário de sleep(), que aguarda por uma duração ("aguardar 10 segundos"), esta função espera até um momento ("aguardar até 14:30:00"). Este artigo explica sua sintaxe, valor de retorno, casos especiais e quando utilizá-la.

Sintaxe

time_sleep_until(float $timestamp): bool

• $timestamp — o timestamp Unix (segundos desde a época) em que o script deve ser retomado. Como o parâmetro é um float, você pode passar segundos fracionários para precisão abaixo de um segundo (ex.: time() + 2.5).
• Valor de retorno — retorna true em caso de sucesso e false em caso de falha.

Se o timestamp fornecido já estiver no passado, a função retorna imediatamente sem pausar. No PHP 8, ela retorna false e emite um aviso; no PHP 7, também retornava false. De qualquer forma, o script não bloqueia — portanto, não confie na chamada para "aguardar" quando o tempo alvo já passou.

Como usar a função time_sleep_until()

Chame a função e passe o timestamp em que o script deve ser retomado. O padrão mais comum é adicionar um deslocamento ao tempo atual retornado por time():

Aqui, time() + 10 é um timestamp Unix absoluto dez segundos no futuro. time_sleep_until() bloqueia até que o relógio do sistema atinja esse valor, então a execução continua e imprime a mensagem final.

Aguardando o próximo minuto completo

Como você passa um tempo absoluto, time_sleep_until() é ideal para alinhar trabalho a um limite de relógio — por exemplo, executar uma tarefa exatamente quando o próximo minuto começar:

<?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";
?>

A expressão $now - ($now % 60) + 60 remove os segundos do timestamp atual e adiciona 60, fornecendo o timestamp do próximo minuto. Isso é mais preciso do que sleep(60), que derivaria se o script fosse iniciado no meio de um minuto.

Precisão abaixo de um segundo

Passar um timestamp fracionário atrasa por uma fração de segundo:

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

Para pausar por uma duração em vez de até um momento absoluto, prefira usleep() (microssegundos) ou time_nanosleep() (nanossegundos).

time_sleep_until() vs sleep()

Escolha time_sleep_until() quando você souber o horário exato do relógio em que deseja retomar; escolha sleep()/usleep() quando apenas importar quanto tempo pausar. Você pode construir o timestamp alvo com auxiliares como time() ou microtime().

Considerações de desempenho

time_sleep_until() bloqueia o processo atual até que o tempo alvo seja atingido. Ele usa CPU mínima enquanto aguarda, mas um processo bloqueado ainda é um processo paralisado: em uma requisição web, uma pausa longa pode atingir o limite max_execution_time ou o timeout de requisição do servidor web e produzir um erro 504. Portanto, é mais adequado para scripts CLI, cron jobs e processos worker do que para requisições voltadas ao usuário. Evite chamá-lo em caminhos críticos de desempenho e mantenha a espera curta em qualquer contexto HTTP.

Conclusão

time_sleep_until() pausa um script até um timestamp Unix absoluto, tornando-o a ferramenta certa para atrasos alinhados ao relógio, onde sleep() permitiria apenas especificar uma duração. Lembre-se de que ele retorna true/false, nunca bloqueia para um timestamp passado, aceita segundos fracionários e ocupa todo o processo enquanto aguarda — portanto, reserve-o para código CLI e worker em vez de requisições web.

Prática