Signatur
Beschreibung
CurlSharePersistentHandle ist eine in PHP 8.4 eingeführte Klasse, die ein persistentes geteiltes cURL-Handle kapselt. Im Gegensatz zum gewöhnlichen CurlShareHandle bleibt ein persistentes Share-Handle über Request-Grenzen hinaus im Speicher erhalten, sofern dies vom jeweiligen SAPI unterstützt wird (z. B. FrankenPHP, Swoole oder andere Long-Running-Prozesse).
Mit einem geteilten Handle können mehrere cURL-Verbindungen gemeinsam auf Daten wie DNS-Cache, SSL-Sessions, Cookies oder HTTP/2-Verbindungen zugreifen. Das vermeidet redundante Verbindungsaufbauten und DNS-Auflösungen, was die Latenz deutlich reduziert und den Durchsatz bei vielen gleichzeitigen oder aufeinanderfolgenden HTTP-Anfragen steigert.
Die Klasse kann nicht direkt per new CurlSharePersistentHandle() instanziiert werden. Stattdessen wird sie über die Funktion curl_share_init_persistent() erzeugt, welche einen String-Schlüssel zur Identifikation des persistenten Handles entgegennimmt. Wird dieselbe Funktion mit demselben Schlüssel erneut aufgerufen, wird das bereits vorhandene Handle zurückgegeben.
Das Handle wird anschließend wie ein normales Share-Handle mit curl_share_setopt() konfiguriert und dann über curl_setopt() mit der Option CURLOPT_SHARE einem oder mehreren cURL-Handles zugewiesen. Da das Handle persistent ist, darf es nicht manuell mit curl_share_close() geschlossen werden.
Beispiele
Persistentes Share-Handle für DNS- und SSL-Wiederverwendung
<?php
// Persistentes Share-Handle erzeugen oder vorhandenes abrufen
$shareHandle = curl_share_init_persistent('my_app_share');
// DNS-Cache und SSL-Sessions teilen
curl_share_setopt($shareHandle, CURLSHOPT_SHARE, CURL_LOCK_DATA_DNS);
curl_share_setopt($shareHandle, CURLSHOPT_SHARE, CURL_LOCK_DATA_SSL_SESSION);
// Normales cURL-Handle erstellen und Share-Handle zuweisen
$ch = curl_init('https://example.com/api/data');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_SHARE, $shareHandle);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
Mehrere Anfragen mit gemeinsamem Share-Handle senden
<?php
// Persistentes Handle mit eindeutigem Schlüssel abrufen/erstellen
$shareHandle = curl_share_init_persistent('http_pool');
curl_share_setopt($shareHandle, CURLSHOPT_SHARE, CURL_LOCK_DATA_DNS);
curl_share_setopt($shareHandle, CURLSHOPT_SHARE, CURL_LOCK_DATA_CONNECT);
$urls = [
'https://httpbin.org/get?a=1',
'https://httpbin.org/get?a=2',
'https://httpbin.org/get?a=3',
];
foreach ($urls as $url) {
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_SHARE, $shareHandle);
$result = curl_exec($ch);
$info = curl_getinfo($ch);
curl_close($ch);
// DNS-Auflösung wird ab der zweiten Anfrage aus dem Cache bedient
printf("URL: %s | Namelookup: %.4f s\n", $url, $info['namelookup_time']);
}
// Wichtig · Fallstricke
Nicht manuell schließen: Da das Handle persistent ist und von der Engine verwaltet wird, darf curl_share_close() auf einem CurlSharePersistentHandle nicht aufgerufen werden. Dies führt zu einem Fehler.
SAPI-Abhängigkeit: Persistente Handles sind nur in Long-Running-SAPIs (z. B. FrankenPHP, Swoole, ReactPHP-Umgebungen) wirklich nützlich. Im klassischen PHP-FPM oder CGI-Betrieb wird das Handle nach jedem Request ohnehin freigegeben, sodass die Persistenz keinen Vorteil bietet.
Thread-Sicherheit: Bei der Verwendung in Multi-Thread-Umgebungen ist darauf zu achten, dass gleichzeitige Zugriffe auf dasselbe Share-Handle intern durch cURL synchronisiert werden. Dies kann bei sehr vielen parallelen Threads zu Contention führen. In solchen Fällen empfiehlt sich ggf. die Verwendung mehrerer Share-Handles mit unterschiedlichen Schlüsseln.
Schlüssel-Eindeutigkeit: Der Schlüssel, der an curl_share_init_persistent() übergeben wird, sollte anwendungsweit eindeutig und sprechend gewählt werden, da er zur Identifikation des Handles im Prozess-Speicher dient.