sleep()

La fonction PHP sleep() suspend l'exécution de votre script pendant un nombre fixe de secondes entières. Cet article explique sa syntaxe et ses valeurs de retour, les situations où retarder un script est réellement utile, les pièges liés au blocage et aux signaux, et comment sleep() se compare à ses cousines de précision inférieure à la seconde.

Syntaxe

sleep(int $seconds): int|false

• $seconds — le nombre de secondes entières pendant lesquelles suspendre le script. Il doit s'agir d'un entier non négatif ; passer une valeur négative déclenche une erreur.
• Valeur de retour — sleep() retourne 0 en cas de succès. Si l'appel est interrompu par un signal (par exemple, une alarme ou un gestionnaire Ctrl+C sur la CLI), il retourne le nombre de secondes restantes à attendre, qui est un entier positif non nul. Il retourne false uniquement si l'appel échoue complètement.

Comme sleep() n'accepte que des entiers, le délai minimal qu'elle peut produire est d'une seconde. Pour un contrôle plus fin, utilisez usleep() (microsecondes) ou time_nanosleep() (nanosecondes).

Utilisation de base

Appelez sleep() en passant le nombre de secondes à attendre. Tout ce qui suit l'appel ne s'exécute qu'une fois le délai écoulé :

Le script affiche le premier message, se bloque pendant cinq secondes, puis affiche le second. Vous pouvez clairement observer l'écart en mesurant le temps d'exécution du script :

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

Cela affiche Waited about 2 seconds, confirmant la pause. (Voir microtime() pour mesurer le temps écoulé.)

Quand utiliser sleep() ?

sleep() est particulièrement utile dans les scripts en ligne de commande et les scripts d'arrière-plan où une courte pause est intentionnelle :

• Interrogation avec délai — vérification d'une file d'attente, d'un fichier ou d'une API à intervalles réguliers plutôt que dans une boucle serrée et gourmande en CPU.
• Limitation de débit / être un bon citoyen des API — espacement des requêtes pour ne pas dépasser la limite de débit d'un service tiers.
• Recul avant nouvelle tentative — attente avant de réessayer une opération échouée, souvent avec un délai croissant.

Voici un modèle simple de nouvelle tentative avec recul progressif :

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

Cela affiche deux messages d'échec (en attendant 1s puis 2s) et finalement Succeeded on attempt 3.

sleep() bloque l'ensemble du processus

sleep() est un appel bloquant : rien d'autre ne se produit dans ce processus PHP pendant qu'il attend. Cela a deux implications importantes :

• N'appelez jamais sleep() dans une requête web normale. Une requête en attente garde un worker PHP-FPM (et souvent une connexion navigateur) occupé à ne rien faire, ce qui nuit au débit et peut déclencher les limites de délai d'expiration des requêtes. Les pauses appartiennent aux scripts CLI, aux tâches cron et aux workers de file d'attente.
• Elle ne cède pas la main à d'autre code. Si vous avez besoin d'attendre sans bloquer, c'est le rôle d'une boucle événementielle ou d'un runtime asynchrone, pas de sleep().

Gestion des interruptions de sommeil

Sur la CLI, un signal peut écourter un sommeil. Quand cela se produit, sleep() retourne les secondes restantes au lieu de 0, vous permettant de reprendre l'attente si vous le souhaitez :

<?php
$remaining = sleep(5);

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

Lorsque le sommeil se termine normalement, $remaining vaut 0 et le script affiche Slept the full duration.

Délais inférieurs à la seconde : usleep() et ses variantes

Comme sleep() n'accepte que des secondes entières, PHP offre des alternatives plus précises :

Par exemple, pour limiter une boucle à environ 10 itérations par seconde, faites une pause de 100 000 microsecondes (un dixième de seconde) à chaque passage :

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

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

Cela affiche Tick 1, Tick 2, Tick 3 avec environ un dixième de seconde entre chaque ligne.

Conclusion

sleep() est un moyen fiable de suspendre un script PHP pendant un nombre entier de secondes. Rappelez-vous qu'elle bloque l'ensemble du processus, donc évitez-la dans les requêtes web en production et réservez-la aux outils CLI, aux tâches cron et aux workers — typiquement pour l'interrogation, la limitation de débit et le recul avant nouvelle tentative. Lorsque vous avez besoin d'un minutage plus précis, utilisez usleep(), time_nanosleep() ou time_sleep_until(). Pour en savoir plus sur la gestion du temps en PHP, consultez PHP Date et Heure.

Pratique