curl_multi_add_handle — Funktion · PHP-Referenz

Signatur

curl_multi_add_handle(CurlMultiHandle $multi_handle, CurlHandle $handle): int

Beschreibung

curl_multi_add_handle() registriert ein mit curl_init() erzeugtes cURL-Handle in einem mit curl_multi_init() erstellten Multi-Handle. Dadurch können mehrere HTTP-Verbindungen gleichzeitig – also nicht-blockierend – verarbeitet werden, was die Gesamtlaufzeit bei vielen Anfragen erheblich reduziert.

Typischer Ablauf: Mehrere Einzel-Handles werden konfiguriert (z. B. mit curl_setopt()), dann nacheinander per curl_multi_add_handle() hinzugefügt, anschließend mit curl_multi_exec() ausgeführt und schließlich mit curl_multi_remove_handle() wieder entfernt.

Ein Handle darf gleichzeitig nur einem einzigen Multi-Handle zugeordnet sein. Wird versucht, dasselbe Handle mehreren Multi-Handles zuzuweisen oder es doppelt hinzuzufügen, gibt die Funktion einen Fehlercode zurück.

Diese Funktion ist besonders sinnvoll, wenn viele externe Ressourcen (APIs, Webseiten, Dateien) parallel abgerufen werden sollen, ohne auf jede Antwort einzeln warten zu müssen.

Parameter

Name	Typ	Default	Beschreibung
$multi_handle Pflicht	CurlMultiHandle		Ein gültiges cURL-Multi-Handle, erzeugt mit `curl_multi_init()`.
$handle Pflicht	CurlHandle		Ein reguläres cURL-Handle, erzeugt mit `curl_init()` und typischerweise mit `curl_setopt()` konfiguriert.

Rückgabewert

Typ

int

Beschreibung

Gibt CURLM_OK (0) bei Erfolg zurück. Bei einem Fehler wird ein entsprechender CURLM_*-Fehlercode zurückgegeben, z. B. CURLM_ADDED_ALREADY (7) wenn das Handle bereits hinzugefügt wurde.

Beispiele

Zwei URLs parallel abrufen

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

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

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

// Multi-Handle ausführen
$running = null;
do {
    $status = curl_multi_exec($multiHandle, $running);
    if ($status === CURLM_OK) {
        curl_multi_select($multiHandle);
    }
} while ($running > 0 && $status === CURLM_OK);

// Ergebnisse auslesen und aufräumen
foreach ($handles as $ch) {
    $response = curl_multi_getcontent($ch);
    echo substr($response, 0, 80) . PHP_EOL;
    curl_multi_remove_handle($multiHandle, $ch);
    curl_close($ch);
}

curl_multi_close($multiHandle);

Fehlerbehandlung beim Hinzufügen

<?php
$multiHandle = curl_multi_init();
$ch = curl_init('https://example.com');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$result = curl_multi_add_handle($multiHandle, $ch);

if ($result !== CURLM_OK) {
    echo 'Fehler beim Hinzufügen: ' . curl_multi_strerror($result) . PHP_EOL;
} else {
    echo 'Handle erfolgreich hinzugefügt.' . PHP_EOL;
}

// Versuch, dasselbe Handle nochmals hinzuzufügen
$result2 = curl_multi_add_handle($multiHandle, $ch);
if ($result2 !== CURLM_OK) {
    echo 'Erwarteter Fehler: ' . curl_multi_strerror($result2) . PHP_EOL;
}

curl_multi_remove_handle($multiHandle, $ch);
curl_close($ch);
curl_multi_close($multiHandle);

Handle erfolgreich hinzugefügt. Erwarteter Fehler: about to add a handle to a multi handle that already added to a multi handle

// Wichtig · Fallstricke

Ressourcenverwaltung: Jedes mit curl_multi_add_handle() hinzugefügte Handle muss nach der Verarbeitung explizit mit curl_multi_remove_handle() entfernt und danach mit curl_close() geschlossen werden, um Speicherlecks zu vermeiden.

PHP 8.0+: Ab PHP 8.0 werden cURL-Handles als CurlHandle- bzw. CurlMultiHandle-Objekte repräsentiert; in älteren PHP-Versionen waren es Ressourcen vom Typ resource.

Parallelität: cURL-Multi führt keine echten Threads aus – die parallele Verarbeitung erfolgt über nicht-blockierende I/O (select/epoll). Für CPU-intensive Aufgaben ist curl_multi daher nicht geeignet.

Siehe auch

curl_multi_init curl_multi_remove_handle curl_multi_exec curl_multi_select curl_multi_getcontent curl_multi_close curl_init curl_multi_strerror