sleep — Funktion · PHP-Referenz

Signatur

sleep(int $seconds): int|false

Beschreibung

sleep() pausiert die Ausführung des aktuellen PHP-Skripts für die angegebene Anzahl von ganzen Sekunden. Dies ist nützlich, wenn man Operationen zeitlich steuern möchte, etwa um API-Rate-Limits einzuhalten, Polling-Intervalle umzusetzen oder einfach eine Verzögerung zwischen wiederholten Aktionen einzuführen.

Während des Schlafs verbraucht der PHP-Prozess keine CPU-Zeit, blockiert jedoch den Webserver-Worker-Prozess oder Thread. In einem Web-Kontext mit vielen parallelen Anfragen sollte sleep() daher sparsam eingesetzt werden, da es zur Erschöpfung des Worker-Pools führen kann.

Wenn ein Signal eintrifft, das den Prozess unterbricht (z. B. SIGALRM), kann sleep() vorzeitig beendet werden. In diesem Fall gibt die Funktion die Anzahl der verbleibenden, noch nicht geschlafenen Sekunden zurück. Ist das Script im CLI-Modus und soll präzisere Pausen als ganzzahlige Sekunden benötigen, bietet sich usleep() oder time_nanosleep() an.

Parameter

Name	Typ	Default	Beschreibung
$seconds Pflicht	int		Anzahl der Sekunden, um die die Ausführung verzögert werden soll. Muss ein nicht-negativer ganzzahliger Wert sein; negative Werte lösen seit PHP 8.0 einen `ValueError` aus.

Rückgabewert

Typ

int|false

Beschreibung

Gibt 0 zurück, wenn die Verzögerung vollständig abgelaufen ist. Wurde der Schlaf durch ein Signal unterbrochen, wird die Anzahl der verbleibenden Sekunden zurückgegeben. Bei einem Fehler wird false zurückgegeben.

Beispiele

Einfache Verzögerung von 2 Sekunden

<?php
echo "Start: " . date('H:i:s') . PHP_EOL;
sleep(2);
echo "Ende:  " . date('H:i:s') . PHP_EOL;

Start: 12:00:00 Ende: 12:00:02

Polling mit Verzögerung in einer Schleife (CLI)

<?php
// Simuliertes Polling: Alle 5 Sekunden wird eine Aufgabe geprüft
$maxIterations = 3;
for ($i = 1; $i <= $maxIterations; $i++) {
    echo "Iteration $i: " . date('H:i:s') . " — Prüfe Aufgaben..." . PHP_EOL;
    // Hier käme z. B. ein Datenbank-Check
    if ($i < $maxIterations) {
        sleep(5);
    }
}
echo "Fertig." . PHP_EOL;

Iteration 1: 12:00:00 — Prüfe Aufgaben... Iteration 2: 12:00:05 — Prüfe Aufgaben... Iteration 3: 12:00:10 — Prüfe Aufgaben... Fertig.

API-Rate-Limit einhalten

<?php
$urls = [
    'https://api.example.com/data/1',
    'https://api.example.com/data/2',
    'https://api.example.com/data/3',
];

foreach ($urls as $index => $url) {
    // Simulierter API-Aufruf
    echo "Abrufe: $url" . PHP_EOL;
    // Nach jedem Aufruf (außer dem letzten) 1 Sekunde warten
    if ($index < count($urls) - 1) {
        sleep(1);
    }
}
echo "Alle Daten abgerufen." . PHP_EOL;

Abrufe: https://api.example.com/data/1 Abrufe: https://api.example.com/data/2 Abrufe: https://api.example.com/data/3 Alle Daten abgerufen.

// Wichtig · Fallstricke

Web-Kontext: Im Web-Server-Betrieb (z. B. Apache, Nginx mit PHP-FPM) blockiert sleep() den Worker-Prozess vollständig. Zu viele schlafende Prozesse können zu Ressourcenengpässen führen. Für zeitgesteuerte Hintergrundaufgaben sind Cronjobs oder dedizierte Worker-Prozesse die bessere Wahl.

PHP 8.0+: Negative Werte für $seconds lösen seit PHP 8.0 einen ValueError aus. In früheren Versionen verhielt sich die Funktion bei negativen Werten undefiniert.

Präzisere Pausen: Für Verzögerungen unter einer Sekunde stehen usleep() (Mikrosekunden) und time_nanosleep() (Nanosekunden) zur Verfügung.

max_execution_time: Die Schlafzeit wird unter Unix/Linux nicht auf das max_execution_time-Limit angerechnet, auf Windows hingegen schon. Dies kann zu unerwartetem Timeout-Verhalten führen.

Siehe auch

usleep time_nanosleep time_sleep_until set_time_limit