curl_multi_remove_handle — Funktion · PHP-Referenz

Signatur

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

Beschreibung

curl_multi_remove_handle() entfernt ein zuvor mit curl_multi_add_handle() hinzugefügtes cURL-Handle aus der angegebenen Multi-Handle-Gruppe. Dies ist notwendig, wenn ein einzelner Transfer abgeschlossen ist oder abgebrochen werden soll, ohne die gesamte Multi-Handle-Gruppe zu beenden.

Nach dem Entfernen kann das betroffene cURL-Handle entweder mit curl_close() freigegeben oder mit veränderten Optionen für einen neuen Transfer wiederverwendet werden. Das Multi-Handle selbst bleibt nach dem Aufruf weiterhin aktiv und kann für weitere parallele Transfers genutzt werden.

Typischer Einsatzfall ist das gleichzeitige Ausführen mehrerer HTTP-Anfragen (z. B. Abruf von REST-APIs), bei dem nach Abschluss eines Transfers das entsprechende Handle aus der Gruppe entfernt und die Antwort verarbeitet wird, während andere Transfers noch laufen.

Der Rückgabewert ist eine Integer-Konstante: CURLM_OK (0) bei Erfolg, andernfalls ein Fehlercode wie CURLM_BAD_EASY_HANDLE oder CURLM_BAD_HANDLE.

Parameter

Name	Typ	Default	Beschreibung
$multi_handle Pflicht	CurlMultiHandle		Das Multi-Handle-Objekt, das mit `curl_multi_init()` erstellt wurde.
$handle Pflicht	CurlHandle		Das einzelne cURL-Handle (erstellt mit `curl_init()`), das aus der Gruppe entfernt werden soll.

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_BAD_EASY_HANDLE, wenn das Handle nicht Teil der Gruppe ist.

Beispiele

Parallele HTTP-Anfragen mit curl_multi und sauberem Aufräumen

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

$multiHandle = curl_multi_init();
$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($multiHandle, $ch);
    $handles[$i] = $ch;
}

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

// Ergebnisse verarbeiten und Handles entfernen
foreach ($handles as $i => $ch) {
    $response = curl_multi_getcontent($ch);
    echo "Antwort $i: " . substr($response, 0, 80) . PHP_EOL;

    // Handle aus der Gruppe entfernen, bevor es geschlossen wird
    $status = curl_multi_remove_handle($multiHandle, $ch);
    if ($status !== CURLM_OK) {
        echo "Fehler beim Entfernen von Handle $i: $status" . PHP_EOL;
    }
    curl_close($ch);
}

curl_multi_close($multiHandle);
?>

Antwort 0: {"args": {"id": "1"}, ... Antwort 1: {"args": {"id": "2"}, ... Antwort 2: {"args": {"id": "3"}, ...

Dynamisches Entfernen abgeschlossener Handles während der Ausführung

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

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

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

$running = null;
do {
    $status = curl_multi_exec($multiHandle, $running);
    // Auf Aktivität warten (verhindert busy-waiting)
    if ($running > 0) {
        curl_multi_select($multiHandle);
    }

    // Fertige Handles sofort verarbeiten
    while ($info = curl_multi_info_read($multiHandle)) {
        if ($info['msg'] === CURLMSG_DONE) {
            $finishedHandle = $info['handle'];
            $content = curl_multi_getcontent($finishedHandle);
            echo 'Transfer abgeschlossen, Bytes: ' . strlen($content) . PHP_EOL;

            // Sofort aus der Gruppe entfernen
            curl_multi_remove_handle($multiHandle, $finishedHandle);
            curl_close($finishedHandle);
        }
    }
} while ($running > 0);

curl_multi_close($multiHandle);
?>

Transfer abgeschlossen, Bytes: 312 Transfer abgeschlossen, Bytes: 312

// Wichtig · Fallstricke

Wichtige Reihenfolge: Ein cURL-Handle muss zuerst mit curl_multi_remove_handle() aus der Gruppe entfernt werden, bevor curl_close() aufgerufen wird. Wird curl_close() zuerst aufgerufen, während das Handle noch im Multi-Handle registriert ist, kann dies zu undefiniertem Verhalten oder Speicherproblemen führen.

Wiederverwendung: Nach dem Entfernen kann ein Handle mit neuen Optionen versehen und erneut per curl_multi_add_handle() zur Gruppe hinzugefügt werden — dies ist effizienter als das Erstellen eines neuen Handles.

PHP-Versionen: Ab PHP 8.0 werden CurlMultiHandle und CurlHandle als eigene Objekttypen verwendet. In PHP 7.x und früher waren diese Werte Ressourcen vom Typ resource.

Siehe auch

curl_multi_init curl_multi_add_handle curl_multi_exec curl_multi_info_read curl_multi_close curl_close