Signatur
Beschreibung
curl_upkeep() führt verbindungserhaltende Maßnahmen für ein gegebenes cURL-Handle durch. Aktuell betrifft dies vor allem HTTP/2-Verbindungen: Die Funktion sendet einen PING-Frame, um sicherzustellen, dass die Verbindung zum Server noch aktiv ist und nicht vom Netzwerk oder einem zwischengeschalteten Proxy stillschweigend getrennt wurde.
Die Funktion ist besonders nützlich bei langlebigen cURL-Handles (z. B. in persistenten Verbindungspools oder bei Keep-Alive-Verbindungen), bei denen längere Pausen zwischen den Anfragen auftreten können. Ohne regelmäßigen Upkeep könnten solche Verbindungen intern als geschlossen markiert werden, was zu Fehlern bei nachfolgenden Anfragen führt.
In typischen Szenarien – etwa in Worker-Prozessen, Daemons oder CLI-Skripten, die cURL-Verbindungen über längere Zeiträume offen halten – sollte curl_upkeep() in regelmäßigen Abständen aufgerufen werden, um die Verbindungsintegrität sicherzustellen.
Die Funktion gibt true zurück, wenn alle Upkeep-Maßnahmen erfolgreich durchgeführt wurden, und false bei einem Fehler. Sie ändert den Status des Handles nicht grundlegend und ist daher sicher zwischen zwei Anfragen aufrufbar.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $handle Pflicht | CurlHandle | Ein gültiges cURL-Handle, das zuvor mit curl_init() erstellt wurde. |
Rückgabewert
true zurück, wenn alle Verbindungserhaltungs-Prüfungen erfolgreich waren, andernfalls false.Beispiele
Verbindung in einem langlebigen Worker am Leben erhalten
<?php
$ch = curl_init('https://example.com/api/stream');
curl_setopt($ch, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_2_0);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
// Erste Anfrage ausführen
$result = curl_exec($ch);
echo "Erste Antwort erhalten.\n";
// Simuliere eine Pause (z. B. Verarbeitungszeit)
sleep(5);
// Verbindung aktiv halten
if (curl_upkeep($ch)) {
echo "Upkeep erfolgreich – Verbindung ist noch aktiv.\n";
} else {
echo "Upkeep fehlgeschlagen: " . curl_error($ch) . "\n";
}
// Zweite Anfrage mit demselben Handle
curl_setopt($ch, CURLOPT_URL, 'https://example.com/api/data');
$result2 = curl_exec($ch);
echo "Zweite Antwort erhalten.\n";
curl_close($ch);Einsatz in einer periodischen Schleife (Daemon-Muster)
<?php
$ch = curl_init('https://example.com/api/status');
curl_setopt($ch, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_2_0);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$lastRequestTime = time();
$upkeepInterval = 30; // Sekunden
while (true) {
$now = time();
// Verbindung alle 30 Sekunden aktiv halten
if (($now - $lastRequestTime) >= $upkeepInterval) {
if (!curl_upkeep($ch)) {
error_log('cURL-Upkeep fehlgeschlagen: ' . curl_error($ch));
}
$lastRequestTime = $now;
}
// Hier eigentliche Arbeit des Daemons ...
sleep(1);
// Abbruchbedingung für das Beispiel
break;
}
curl_close($ch);
echo "Daemon-Schleife beendet.\n";// Wichtig · Fallstricke
HTTP/2-spezifisch: Aktuell hat curl_upkeep() nur bei HTTP/2-Verbindungen eine messbare Wirkung (PING-Frame). Bei HTTP/1.x-Verbindungen ist der Aufruf zwar erlaubt, führt aber zu keinen zusätzlichen Aktionen.
Verfügbarkeit: Die Funktion steht erst ab PHP 8.2.0 zur Verfügung und erfordert eine libcurl-Version, die diese Funktionalität unterstützt (libcurl >= 7.62.0). Auf älteren Systemen ist sie nicht vorhanden.
Kein Ersatz für Fehlerbehandlung: curl_upkeep() garantiert nicht, dass die nächste Anfrage erfolgreich sein wird. Verbindungsfehler bei curl_exec() sollten weiterhin separat behandelt werden.