Signatur
Beschreibung
CurlShareHandle ist eine opake Klasse, die in PHP 8.0.0 eingeführt wurde, um den bisherigen resource-Typ für cURL-Share-Handles zu ersetzen. Instanzen dieser Klasse werden ausschließlich durch curl_share_init() erstellt und können nicht manuell instanziiert werden.
Ein cURL-Share-Handle ermöglicht es, bestimmte Daten – wie DNS-Cache, SSL-Session-Daten oder Cookies – zwischen mehreren CurlHandle-Instanzen gemeinsam zu nutzen. Dies ist besonders nützlich bei Anwendungen, die viele parallele oder sequenzielle HTTP-Anfragen durchführen und dabei Overhead durch wiederholte DNS-Auflösungen oder SSL-Handshakes vermeiden wollen.
Der Typ der gemeinsam genutzten Daten wird über curl_share_setopt() mit Konstanten wie CURL_LOCK_DATA_DNS, CURL_LOCK_DATA_SSL_SESSION oder CURL_LOCK_DATA_COOKIE festgelegt. Ein Share-Handle wird einem einzelnen cURL-Handle über curl_setopt($ch, CURLOPT_SHARE, $sh) zugewiesen.
Nach Beendigung der Nutzung sollte das Share-Handle mit curl_share_close() explizit freigegeben werden, obwohl dies ab PHP 8.0 durch den Garbage Collector automatisch übernommen werden kann. Die Klasse selbst bietet keine öffentlichen Methoden oder Eigenschaften – die gesamte Steuerung erfolgt über die zugehörigen curl_share_*-Funktionen.
Beispiele
DNS-Cache zwischen mehreren cURL-Handles teilen
<?php
// Share-Handle erstellen
$sh = curl_share_init();
// DNS-Cache gemeinsam nutzen
curl_share_setopt($sh, CURLSHOPT_SHARE, CURL_LOCK_DATA_DNS);
$urls = [
'https://example.com',
'https://example.org',
'https://example.net',
];
foreach ($urls as $url) {
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
// Share-Handle zuweisen
curl_setopt($ch, CURLOPT_SHARE, $sh);
$response = curl_exec($ch);
if ($response === false) {
echo 'Fehler bei ' . $url . ': ' . curl_error($ch) . PHP_EOL;
} else {
echo 'Antwort von ' . $url . ' erhalten (' . strlen($response) . ' Bytes)' . PHP_EOL;
}
curl_close($ch);
}
// Share-Handle freigeben
curl_share_close($sh);SSL-Session und Cookie-Daten gemeinsam nutzen
<?php
$sh = curl_share_init();
// SSL-Session und Cookies zwischen Handles teilen
curl_share_setopt($sh, CURLSHOPT_SHARE, CURL_LOCK_DATA_SSL_SESSION);
curl_share_setopt($sh, CURLSHOPT_SHARE, CURL_LOCK_DATA_COOKIE);
// Typ-Prüfung: CurlShareHandle-Instanz
if ($sh instanceof CurlShareHandle) {
echo 'Share-Handle erfolgreich erstellt.' . PHP_EOL;
}
$ch1 = curl_init('https://httpbin.org/cookies/set?foo=bar');
curl_setopt($ch1, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch1, CURLOPT_FOLLOWLOCATION, true);
curl_setopt($ch1, CURLOPT_SHARE, $sh);
curl_exec($ch1);
curl_close($ch1);
$ch2 = curl_init('https://httpbin.org/cookies');
curl_setopt($ch2, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch2, CURLOPT_SHARE, $sh);
$result = curl_exec($ch2);
echo $result . PHP_EOL;
curl_close($ch2);
curl_share_close($sh);// Wichtig · Fallstricke
Opake Klasse: CurlShareHandle kann nicht mit new CurlShareHandle() instanziiert werden. Die einzige Möglichkeit, eine Instanz zu erhalten, ist der Aufruf von curl_share_init().
Thread-Sicherheit: Das Teilen von Daten zwischen Handles in einem Multi-Thread-Kontext (z. B. mit curl_multi_*) erfordert sorgfältige Synchronisierung. Die CURLSHOPT_LOCKFUNC- und CURLSHOPT_UNLOCKFUNC-Optionen stehen in PHP nicht zur Verfügung, weshalb CurlShareHandle in echter Multithreading-Umgebung mit Vorsicht einzusetzen ist.
Migration von PHP 7: In PHP 7 lieferte curl_share_init() eine resource vom Typ curl_share. Ab PHP 8.0 ist der Rückgabewert eine CurlShareHandle-Instanz. Code, der is_resource() zur Prüfung verwendet, muss auf instanceof CurlShareHandle umgestellt werden.