Signatur
Beschreibung
time_sleep_until() hält die Ausführung des aktuellen PHP-Skripts an, bis der angegebene Unix-Zeitstempel erreicht ist. Im Gegensatz zu sleep() oder usleep(), die eine Dauer als Parameter erwarten, arbeitet diese Funktion mit einem absoluten Zielzeitpunkt. Dies ist besonders nützlich, wenn man zu einem exakten Zeitpunkt fortfahren möchte, unabhängig davon, wie lange vorherige Operationen gedauert haben.
Der Parameter timestamp ist ein float-Wert, wodurch auch Bruchteile von Sekunden angegeben werden können (z. B. microtime(true) + 0.5 für eine halbe Sekunde). Intern verwendet die Funktion nanosleep(), sofern das Betriebssystem dies unterstützt, was eine hohe Genauigkeit ermöglicht.
Ein typischer Anwendungsfall ist das gleichmäßige Taktgeben in Schleifen, etwa bei API-Polling, Rate-Limiting oder bei der Erzeugung zeitlich präziser Ereignisse. Anstatt immer die gleiche Wartezeit zu schlafen und damit Drift zu riskieren, berechnet man den nächsten Ausführungszeitpunkt als absoluten Wert.
Die Funktion gibt false zurück und erzeugt eine Warnung, wenn der angegebene Zeitstempel in der Vergangenheit liegt.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $timestamp Pflicht | float | Der Unix-Zeitstempel (ggf. mit Nachkommastellen für Sub-Sekunden-Präzision), bis zu dem das Skript pausieren soll. Kann mit microtime(true) kombiniert werden. |
Rückgabewert
true zurück, wenn erfolgreich geschlafen wurde. Gibt false zurück und erzeugt eine E_WARNING, wenn der übergebene Zeitstempel in der Vergangenheit liegt.Beispiele
Einfaches Warten bis zu einem Zeitpunkt
<?php
// Skript schläft genau 2 Sekunden, gemessen ab jetzt
$wakeUpAt = microtime(true) + 2.0;
echo "Starte Pause..." . PHP_EOL;
$result = time_sleep_until($wakeUpAt);
echo "Pause beendet. Erfolg: " . ($result ? 'ja' : 'nein') . PHP_EOL;Gleichmäßiges Taktgeben in einer Schleife (Drift-frei)
<?php
// Führt eine Aufgabe exakt jede Sekunde aus, ohne Drift
$interval = 1.0; // Sekunde
$next = microtime(true) + $interval;
for ($i = 1; $i <= 5; $i++) {
// Arbeit erledigen
echo "Iteration $i um " . date('H:i:s') . PHP_EOL;
// Bis zum nächsten Ausführungszeitpunkt schlafen
time_sleep_until($next);
$next += $interval;
}Umgang mit einem Zeitstempel in der Vergangenheit
<?php
// Zeitstempel liegt in der Vergangenheit => Warnung + false
$pastTimestamp = microtime(true) - 5.0;
$result = @time_sleep_until($pastTimestamp);
if ($result === false) {
echo "Fehler: Zeitstempel liegt in der Vergangenheit." . PHP_EOL;
}// Wichtig · Fallstricke
Plattformabhängigkeit: Die Funktion setzt intern auf nanosleep() und ist daher auf Windows möglicherweise weniger präzise oder nicht verfügbar. Unter Linux und macOS funktioniert sie in der Regel zuverlässig.
max_execution_time: Die durch time_sleep_until() verbrachte Schlafzeit wird auf den meisten Systemen (außer Windows) nicht auf das Ausführungszeitlimit angerechnet. Dennoch sollte bei sehr langen Wartezeiten set_time_limit() berücksichtigt werden.
Signal-Unterbrechung: Wenn der Prozess während des Schlafs durch ein Signal unterbrochen wird, kann die Funktion vorzeitig zurückkehren. Der Rückgabewert ist in diesem Fall dennoch true, da kein Fehler im Sinne eines ungültigen Zeitstempels vorlag.