curl_share_init_persistent — Funktion · PHP-Referenz

Signatur

curl_share_init_persistent(string $key): CurlShareHandle

Beschreibung

curl_share_init_persistent() erstellt oder ruft ein bereits existierendes, persistentes cURL-Share-Handle ab, das über den Lebenszyklus eines einzelnen PHP-Requests hinaus im Speicher gehalten wird. Im Gegensatz zu curl_share_init(), das bei jedem Aufruf ein neues Handle erzeugt, wird bei dieser Funktion das Handle anhand des übergebenen $key-Strings identifiziert und bei erneutem Aufruf mit demselben Schlüssel wiederverwendet.

Persistente Share-Handles eignen sich besonders in Umgebungen wie FPM oder anderen Long-Running-Prozessen, in denen zwischen Requests gemeinsame Ressourcen wie DNS-Cache, SSL-Session-Daten oder Cookie-Informationen geteilt werden sollen, ohne diese bei jedem Request neu aufzubauen. Dies kann die Performance bei häufigen HTTP-Anfragen spürbar verbessern.

Das Handle kann wie ein normales Share-Handle mit curl_share_setopt() konfiguriert werden, z. B. um das Teilen von DNS-Cache (CURL_LOCK_DATA_DNS), SSL-Sessions (CURL_LOCK_DATA_SSL_SESSION) oder Cookies (CURL_LOCK_DATA_COOKIE) zu aktivieren. Anschließend wird es einem normalen cURL-Handle über curl_setopt($ch, CURLOPT_SHARE, $sh) zugewiesen.

Wichtig: Da das Handle persistent ist, sollte es nicht mit curl_share_close() geschlossen werden, da es sonst für nachfolgende Requests nicht mehr zur Verfügung steht. Die Verwaltung des Lebenszyklus übernimmt PHP intern.

Parameter

Name	Typ	Default	Beschreibung
$key Pflicht	string		Ein eindeutiger Bezeichner (Schlüssel) für das persistente Share-Handle. Wird bei einem erneuten Aufruf derselbe Schlüssel übergeben, liefert die Funktion das bereits existierende Handle zurück, anstatt ein neues zu erzeugen.

Rückgabewert

Typ

CurlShareHandle

Beschreibung

Gibt ein CurlShareHandle-Objekt zurück. Bei demselben $key wird bei jedem Aufruf dasselbe persistente Handle zurückgegeben.

Beispiele

DNS-Cache zwischen Requests teilen

<?php
// Persistentes Share-Handle einmalig initialisieren und konfigurieren
$sh = curl_share_init_persistent('mein-dns-share');
curl_share_setopt($sh, CURLSHOPT_SHARE, CURL_LOCK_DATA_DNS);
curl_share_setopt($sh, CURLSHOPT_SHARE, CURL_LOCK_DATA_SSL_SESSION);

// cURL-Handle erstellen und das Share-Handle zuweisen
$ch = curl_init('https://example.com/');
curl_setopt($ch, CURLOPT_SHARE, $sh);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);

// Das Share-Handle NICHT schließen – es bleibt für folgende Requests erhalten
echo strlen($response) . ' Bytes empfangen.' . PHP_EOL;

1256 Bytes empfangen.

Mehrere Requests mit gemeinsamem persistentem Share-Handle

<?php
// Persistentes Handle mit einem sprechenden Schlüssel holen (oder erstellen)
$sh = curl_share_init_persistent('api-client-share');
curl_share_setopt($sh, CURLSHOPT_SHARE, CURL_LOCK_DATA_DNS);
curl_share_setopt($sh, CURLSHOPT_SHARE, CURL_LOCK_DATA_COOKIE);

$urls = [
    'https://httpbin.org/get?q=1',
    'https://httpbin.org/get?q=2',
    'https://httpbin.org/get?q=3',
];

foreach ($urls as $url) {
    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_SHARE, $sh);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    $result = curl_exec($ch);
    echo $url . ' => ' . curl_getinfo($ch, CURLINFO_HTTP_CODE) . PHP_EOL;
    curl_close($ch);
}
// $sh wird nicht geschlossen – bleibt persistent für den nächsten Request

https://httpbin.org/get?q=1 => 200 https://httpbin.org/get?q=2 => 200 https://httpbin.org/get?q=3 => 200

// Wichtig · Fallstricke

Nicht schließen: Persistente Share-Handles dürfen nicht mit curl_share_close() geschlossen werden. Anderenfalls steht das Handle für nachfolgende PHP-Requests nicht mehr zur Verfügung und muss neu erzeugt werden, was den Performance-Vorteil zunichte macht.

Thread-Sicherheit: In Multithread-Umgebungen (z. B. Apache mit Threads) muss beachtet werden, dass das persistente Handle von mehreren Threads gleichzeitig genutzt werden kann. cURL sichert den Zugriff intern ab, solange die Share-Optionen korrekt gesetzt sind.

Verfügbarkeit: Diese Funktion ist erst ab PHP 8.4.0 verfügbar. In älteren PHP-Versionen muss curl_share_init() verwendet werden, wobei dann keine echte Persistenz über Requests hinweg besteht.

Schlüsselwahl: Der $key sollte so gewählt werden, dass er das Nutzungsszenario eindeutig beschreibt (z. B. nach API-Endpunkt oder Client-Profil), um unbeabsichtigtes Teilen von Session-Daten zwischen unterschiedlichen Verwendungszwecken zu vermeiden.

Siehe auch

curl_share_init curl_share_setopt curl_share_close curl_setopt curl_init