sleep()

La funzione PHP sleep() mette in pausa l'esecuzione dello script per un numero fisso di secondi interi. Questo articolo spiega la sua sintassi e i valori restituiti, quando è utile ritardare uno script, le insidie legate al blocco e ai segnali, e come sleep() si confronta con le sue varianti sub-secondo.

Sintassi

sleep(int $seconds): int|false

• $seconds — il numero di secondi interi per cui sospendere lo script. Deve essere un intero non negativo; passare un valore negativo genera un errore.
• Valore restituito — sleep() restituisce 0 in caso di successo. Se la chiamata viene interrotta da un segnale (ad esempio, un allarme o un handler Ctrl+C da CLI), restituisce il numero di secondi rimanenti, che è un intero positivo non zero. Restituisce false solo se la chiamata fallisce completamente.

Poiché sleep() accetta solo interi, il ritardo minimo che può produrre è di un secondo. Per un controllo più preciso, usa usleep() (microsecondi) o time_nanosleep() (nanosecondi).

Utilizzo di base

Chiama sleep() e passa il numero di secondi da attendere. Tutto ciò che segue la chiamata viene eseguito solo dopo che il ritardo è trascorso:

Lo script stampa il primo messaggio, si blocca per cinque secondi, poi stampa il secondo. Puoi vedere chiaramente la pausa misurando il tempo di esecuzione dello script:

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

L'output è Waited about 2 seconds, confermando la pausa. (Vedi microtime() per misurare il tempo trascorso.)

Quando usare sleep()?

sleep() è più utile negli script da riga di comando e in background, dove una breve pausa è intenzionale:

• Polling con ritardo — controllare una coda, un file o un API a intervalli regolari invece di un loop stretto e dispendioso in termini di CPU.
• Rate limiting / essere un buon cittadino API — distanziare le richieste per non superare il limite di frequenza di terze parti.
• Retry con back-off — attendere prima di riprovare un'operazione fallita, spesso con un ritardo crescente.

Ecco un semplice pattern retry-with-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
}
?>

Questo stampa due messaggi "failed" (attendendo 1s poi 2s) e infine Succeeded on attempt 3.

sleep() blocca l'intero processo

sleep() è una chiamata bloccante: nulla altro accade in quel processo PHP mentre è in attesa. Questo è importante per due ragioni:

• Non chiamare mai sleep() in una normale richiesta web. Una richiesta in attesa mantiene occupato un worker PHP-FPM (e spesso una connessione browser) senza fare nulla, il che riduce il throughput e può superare i limiti di timeout delle richieste. Le pause appartengono agli script CLI, ai cron job e ai worker in coda.
• Non cede il controllo ad altro codice. Se hai bisogno di attendere senza bloccare, il compito spetta a un event loop o a un runtime asincrono, non a sleep().

Gestione dei sleep interrotti

Da CLI, un segnale può interrompere un sleep anticipatamente. Quando accade, sleep() restituisce i secondi rimanenti invece di 0, così puoi riprendere l'attesa se lo desideri:

<?php
$remaining = sleep(5);

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

Quando il sleep termina normalmente, $remaining è 0 e lo script stampa Slept the full duration.

Ritardi sub-secondo: usleep() e simili

Poiché sleep() accetta solo secondi interi, PHP offre alternative più precise:

Ad esempio, per limitare un loop a circa 10 iterazioni al secondo, metti in pausa per 100.000 microsecondi (un decimo di secondo) ad ogni passaggio:

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

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

Questo stampa Tick 1, Tick 2, Tick 3 con circa un decimo di secondo tra ogni riga.

Conclusione

sleep() è un modo affidabile per mettere in pausa uno script PHP per un numero intero di secondi. Ricorda che blocca l'intero processo, quindi tienila fuori dalle richieste web live e riservala agli strumenti CLI, ai cron job e ai worker — tipicamente per polling, rate limiting e retry con back-off. Quando hai bisogno di una temporizzazione più precisa, usa usleep(), time_nanosleep() o time_sleep_until(). Per ulteriori informazioni sull'utilizzo del tempo in PHP, consulta PHP Date and Time.

Pratica