curl_share_setopt — Funktion · PHP-Referenz

Signatur

curl_share_setopt(CurlShareHandle $share_handle, int $option, mixed $value): bool

Beschreibung

curl_share_setopt() konfiguriert ein mit curl_share_init() erzeugtes Share-Handle. Mit einem Share-Handle können mehrere cURL-Transfers bestimmte Daten (z. B. DNS-Cache, Cookies, SSL-Session-IDs) gemeinsam nutzen, was bei vielen parallelen Anfragen an dieselben Hosts die Performance erheblich verbessert.

Das Share-Handle wird zunächst erstellt, dann mit dieser Funktion konfiguriert und schließlich einzelnen cURL-Handles über curl_setopt($ch, CURLOPT_SHARE, $sh) zugewiesen. Alle so verknüpften Handles teilen sich die im Share-Handle aktivierten Ressourcen.

Die wichtigsten Optionen sind CURLSHOPT_SHARE (aktiviert das Teilen eines Datentyps) und CURLSHOPT_UNSHARE (deaktiviert das Teilen wieder). Als Wert wird eine der CURL_LOCK_DATA_*-Konstanten übergeben, z. B. CURL_LOCK_DATA_DNS, CURL_LOCK_DATA_COOKIE oder CURL_LOCK_DATA_SSL_SESSION.

Diese Funktion ist besonders nützlich in Szenarien, in denen mit curl_multi_*-Funktionen viele gleichzeitige HTTP-Anfragen durchgeführt werden und der Overhead für wiederholte DNS-Auflösungen oder SSL-Handshakes reduziert werden soll.

Parameter

Name	Typ	Beschreibung
$share_handle Pflicht	CurlShareHandle	Ein mit `curl_share_init()` erzeugtes cURL-Share-Handle.
$option Pflicht	int	Eine der folgenden Konstanten: `CURLSHOPT_SHARE` – aktiviert das gemeinsame Nutzen eines Datentyps. `CURLSHOPT_UNSHARE` – deaktiviert das gemeinsame Nutzen eines Datentyps.
$value Pflicht	mixed	Der Wert der Option. Bei `CURLSHOPT_SHARE` und `CURLSHOPT_UNSHARE` wird eine `CURL_LOCK_DATA_*`-Konstante erwartet: `CURL_LOCK_DATA_COOKIE` – Cookies teilen. `CURL_LOCK_DATA_DNS` – DNS-Cache teilen. `CURL_LOCK_DATA_SSL_SESSION` – SSL-Session-IDs teilen. `CURL_LOCK_DATA_CONNECT` – Verbindungs-Cache teilen (ab cURL 7.57.0).

Rückgabewert

Typ

bool

Beschreibung

Gibt true bei Erfolg zurück, false bei einem Fehler (z. B. ungültige Option oder Konflikte mit bereits laufenden Transfers).

Beispiele

DNS-Cache zwischen zwei 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);

// Erstes cURL-Handle
$ch1 = curl_init('https://example.com/');
curl_setopt($ch1, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch1, CURLOPT_SHARE, $sh);

// Zweites cURL-Handle – teilt den DNS-Cache mit $ch1
$ch2 = curl_init('https://example.com/page2');
curl_setopt($ch2, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch2, CURLOPT_SHARE, $sh);

$result1 = curl_exec($ch1);
$result2 = curl_exec($ch2);

curl_close($ch1);
curl_close($ch2);
curl_share_close($sh);

echo 'Anfragen abgeschlossen.';

Anfragen abgeschlossen.

Cookies und SSL-Sessions teilen (Multi-Handle-Szenario)

<?php
$sh = curl_share_init();

// Mehrere Datentypen aktivieren
curl_share_setopt($sh, CURLSHOPT_SHARE, CURL_LOCK_DATA_COOKIE);
curl_share_setopt($sh, CURLSHOPT_SHARE, CURL_LOCK_DATA_SSL_SESSION);
curl_share_setopt($sh, CURLSHOPT_SHARE, CURL_LOCK_DATA_DNS);

$mh = curl_multi_init();
$handles = [];

$urls = [
    'https://example.com/api/endpoint1',
    'https://example.com/api/endpoint2',
    'https://example.com/api/endpoint3',
];

foreach ($urls as $url) {
    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_SHARE, $sh); // Share-Handle zuweisen
    curl_multi_add_handle($mh, $ch);
    $handles[] = $ch;
}

// Alle Transfers parallel ausführen
$running = null;
do {
    curl_multi_exec($mh, $running);
    curl_multi_select($mh);
} while ($running > 0);

foreach ($handles as $ch) {
    $response = curl_multi_getcontent($ch);
    echo 'Antwortlänge: ' . strlen($response) . ' Bytes' . PHP_EOL;
    curl_multi_remove_handle($mh, $ch);
    curl_close($ch);
}

curl_multi_close($mh);
curl_share_close($sh);

Antwortlänge: ... Bytes Antwortlänge: ... Bytes Antwortlänge: ... Bytes

// Wichtig · Fallstricke

Achtung bei Threads: cURL-Share-Handles sind nicht thread-sicher ohne eigene Locking-Mechanismen. In PHP-Umgebungen mit Threads (z. B. pthreads) müssen Lock- und Unlock-Callbacks über CURLSHOPT_LOCKFUNC und CURLSHOPT_UNLOCKFUNC gesetzt werden, um Race Conditions zu vermeiden.

Ein Share-Handle darf nicht verändert werden, solange es von einem aktiven cURL-Handle verwendet wird. Andernfalls ist das Verhalten undefiniert. Änderungen erst nach Abschluss aller Transfers vornehmen.

Ab PHP 8.0 ist der Typ des Parameters $share_handle von resource auf CurlShareHandle (ein echtes Objekt) geändert worden.

Siehe auch

curl_share_init curl_share_close curl_share_errno curl_share_strerror curl_setopt curl_multi_init