curl_multi_setopt — Funktion · PHP-Referenz

Signatur

curl_multi_setopt(CurlMultiHandle $multi_handle, int $option, mixed $value): bool

Beschreibung

curl_multi_setopt() ermöglicht die Konfiguration eines cURL-Multi-Handles, das mit curl_multi_init() erstellt wurde. Über verschiedene Optionskonstanten lässt sich steuern, wie parallele Übertragungen intern verwaltet werden – etwa die maximale Anzahl gleichzeitig geöffneter Verbindungen, das Pipelining-Verhalten oder ein benutzerdefinierter Socket-Callback.

Typische Anwendungsfälle sind das gleichzeitige Abrufen mehrerer URLs (z. B. API-Anfragen oder Web-Scraping), bei denen eine Optimierung der Verbindungsverwaltung die Gesamtlaufzeit deutlich reduzieren kann. Besonders relevant sind die Optionen CURLMOPT_MAXCONNECTS (maximale gleichzeitige Verbindungen im Cache), CURLMOPT_PIPELINING (HTTP-Pipelining und HTTP/2-Multiplexing) sowie CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE für das Tuning von Pipelining-Schwellwerten.

Die Funktion entspricht der C-Funktion curl_multi_setopt() aus der libcurl-Bibliothek. Die verfügbaren Optionskonstanten beginnen mit dem Präfix CURLMOPT_ und müssen von CURLOPT_-Einzelhandle-Optionen unterschieden werden. Das Mischen der beiden Konstantengruppen führt zu Fehlern oder unerwartetem Verhalten.

Parameter

Name	Typ	Beschreibung
$multi_handle Pflicht	CurlMultiHandle	Ein gültiges cURL-Multi-Handle, erzeugt mit `curl_multi_init()`.
$option Pflicht	int	Eine `CURLMOPT_*`-Konstante, die bestimmt, welche Option gesetzt wird. Gültige Werte sind z. B. `CURLMOPT_PIPELINING`, `CURLMOPT_MAXCONNECTS` oder `CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE`.
$value Pflicht	mixed	Der Wert der Option. Der erwartete Typ hängt von der gewählten Option ab: bei `CURLMOPT_MAXCONNECTS` ein `int`, bei `CURLMOPT_PIPELINING` ein Bitfeld als `int`, bei Callback-Optionen ein `callable`.

Rückgabewert

Typ

bool

Beschreibung

Gibt true bei Erfolg zurück, false bei einem Fehler (z. B. ungültige Option oder ungültiges Handle).

Beispiele

Mehrere URLs parallel abrufen mit begrenzten Verbindungen

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

$mh = curl_multi_init();

// Maximal 2 Verbindungen gleichzeitig im Verbindungs-Cache
curl_multi_setopt($mh, CURLMOPT_MAXCONNECTS, 2);

$handles = [];
foreach ($urls as $i => $url) {
    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_TIMEOUT, 10);
    curl_multi_add_handle($mh, $ch);
    $handles[$i] = $ch;
}

$running = null;
do {
    curl_multi_exec($mh, $running);
    curl_multi_select($mh);
} while ($running > 0);

foreach ($handles as $i => $ch) {
    $response = curl_multi_getcontent($ch);
    echo "URL $i: " . strlen($response) . " Bytes empfangen\n";
    curl_multi_remove_handle($mh, $ch);
    curl_close($ch);
}

curl_multi_close($mh);

URL 0: 348 Bytes empfangen URL 1: 348 Bytes empfangen URL 2: 348 Bytes empfangen

HTTP/2-Multiplexing via CURLMOPT_PIPELINING aktivieren

<?php
$mh = curl_multi_init();

// CURLPIPE_MULTIPLEX (2) aktiviert HTTP/2-Multiplexing
// CURLPIPE_HTTP1 (1) aktiviert HTTP/1.1-Pipelining
$result = curl_multi_setopt($mh, CURLMOPT_PIPELINING, CURLPIPE_MULTIPLEX);

if ($result) {
    echo "HTTP/2 Multiplexing erfolgreich aktiviert.\n";
} else {
    echo "Fehler beim Setzen der Option.\n";
}

$urls = [
    'https://example.com/',
    'https://example.com/about',
];

$handles = [];
foreach ($urls as $url) {
    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_2_0);
    curl_multi_add_handle($mh, $ch);
    $handles[] = $ch;
}

$running = null;
do {
    curl_multi_exec($mh, $running);
    curl_multi_select($mh);
} while ($running > 0);

foreach ($handles as $ch) {
    echo strlen(curl_multi_getcontent($ch)) . " Bytes\n";
    curl_multi_remove_handle($mh, $ch);
    curl_close($ch);
}

curl_multi_close($mh);

HTTP/2 Multiplexing erfolgreich aktiviert. 1256 Bytes 987 Bytes

// Wichtig · Fallstricke

Achtung: Verwechsle CURLMOPT_*-Konstanten nicht mit CURLOPT_*-Einzelhandle-Konstanten. Das Übergeben falscher Konstantenwerte führt zu unerwartetem Verhalten oder gibt false zurück, ohne eine PHP-Warnung auszulösen.

Verfügbarkeit: Die Option CURLMOPT_PIPELINING mit dem Wert CURLPIPE_MULTIPLEX erfordert eine libcurl-Version ≥ 7.43.0. CURLMOPT_PUSHFUNCTION (Server-Push-Callback für HTTP/2) ist erst ab libcurl 7.44.0 und PHP 7.1.0 verfügbar. Prüfe die installierte Version via curl_version().

Das Handle muss mit curl_multi_init() erstellt worden sein. Ein bereits geschlossenes Handle führt zu einer TypeError-Exception (ab PHP 8.0) statt zu einem einfachen false.

Siehe auch

curl_multi_init curl_multi_exec curl_multi_add_handle curl_multi_close curl_setopt curl_version