time_sleep_until()

La fonction PHP time_sleep_until() met en pause un script jusqu'à un point absolu dans le temps, exprimé sous forme d'horodatage Unix. Contrairement à sleep(), qui attend une durée ("dormir 10 secondes"), cette fonction attend jusqu'à un moment précis ("dormir jusqu'à 14:30:00"). Cet article explique sa syntaxe, sa valeur de retour, ses cas particuliers et quand l'utiliser.

Syntaxe

time_sleep_until(float $timestamp): bool

• $timestamp — l'horodatage Unix (secondes depuis l'époque) auquel le script doit reprendre. Comme le paramètre est de type float, vous pouvez passer des secondes fractionnaires pour une précision inférieure à la seconde (par exemple time() + 2.5).
• Valeur de retour — retourne true en cas de succès et false en cas d'échec.

Si l'horodatage fourni est déjà dans le passé, la fonction retourne immédiatement sans mettre en pause. En PHP 8, elle retourne false et émet un avertissement ; en PHP 7, elle retournait également false. Dans tous les cas, votre script ne se bloque pas — ne comptez donc pas sur cet appel pour "attendre" si le temps cible est dépassé.

Comment utiliser la fonction time_sleep_until()

Appelez la fonction en lui passant l'horodatage auquel le script doit reprendre. Le schéma le plus courant consiste à ajouter un décalage au temps actuel retourné par time() :

Ici, time() + 10 est un horodatage Unix absolu dix secondes dans le futur. time_sleep_until() bloque jusqu'à ce que l'horloge système atteigne cette valeur, puis l'exécution reprend et affiche le message final.

Attendre la prochaine minute entière

Comme vous passez un temps absolu, time_sleep_until() est idéale pour aligner le travail sur une limite d'horloge — par exemple, exécuter une tâche exactement au début de la prochaine minute :

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

L'expression $now - ($now % 60) + 60 supprime les secondes de l'horodatage actuel et ajoute 60, donnant l'horodatage de la prochaine minute. C'est plus précis que sleep(60), qui dériverait si le script démarrait en cours de minute.

Précision inférieure à la seconde

Passer un horodatage fractionnaire permet de différer d'une fraction de seconde :

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

Pour mettre en pause pendant une durée plutôt que jusqu'à un moment absolu, préférez usleep() (microsecondes) ou time_nanosleep() (nanosecondes).

time_sleep_until() vs sleep()

Choisissez time_sleep_until() lorsque vous connaissez l'heure exacte à laquelle vous souhaitez reprendre ; choisissez sleep()/usleep() lorsque seule la durée de la pause vous importe. Vous pouvez construire l'horodatage cible à l'aide d'assistants tels que time() ou microtime().

Considérations de performance

time_sleep_until() bloque le processus courant jusqu'à ce que le temps cible soit atteint. Elle utilise très peu de CPU pendant l'attente, mais un processus bloqué reste un processus à l'arrêt : dans une requête web, une longue pause peut atteindre la limite max_execution_time ou le délai d'expiration du serveur web et produire une erreur 504. Elle convient donc mieux aux scripts CLI, aux tâches cron et aux processus workers qu'aux requêtes destinées aux utilisateurs. Évitez de l'appeler dans des chemins critiques pour les performances, et maintenez l'attente courte dans tout contexte HTTP.

Conclusion

time_sleep_until() met en pause un script jusqu'à un horodatage Unix absolu, ce qui en fait l'outil idéal pour les délais alignés sur l'horloge, là où sleep() ne permet de spécifier qu'une durée. N'oubliez pas qu'elle retourne true/false, ne bloque jamais pour un horodatage passé, accepte des secondes fractionnaires et immobilise l'ensemble du processus pendant l'attente — réservez-la donc aux scripts CLI et au code worker plutôt qu'aux requêtes web.

Pratique