curl_copy_handle — Funktion · PHP-Referenz

Signatur

curl_copy_handle(CurlHandle $handle): CurlHandle|false

Beschreibung

curl_copy_handle() erzeugt eine vollständige Kopie eines cURL-Handles, einschließlich aller zuvor mit curl_setopt() oder curl_setopt_array() gesetzten Optionen. Das neue Handle ist vollständig unabhängig vom Original – Änderungen an einem der Handles wirken sich nicht auf das andere aus.

Diese Funktion ist besonders nützlich, wenn mehrere Requests mit überwiegend gleichen Einstellungen (z. B. gemeinsame Header, Timeouts, Authentifizierungsdaten) durchgeführt werden sollen, aber jeweils eine andere URL oder ein anderer POST-Body benötigt wird. Statt jedes Mal alle Optionen neu zu setzen, kopiert man ein Basis-Handle und passt nur die abweichenden Einstellungen an.

Das kopierte Handle muss – genau wie das Original – am Ende mit curl_close() geschlossen werden, um Ressourcen freizugeben. Ab PHP 8.0 gibt die Funktion ein CurlHandle-Objekt zurück; in früheren Versionen war es eine Ressource vom Typ resource.

Typischer Einsatz ist auch in Verbindung mit Multi-cURL (curl_multi_init()), wenn mehrere parallele Anfragen mit gemeinsamer Basiskonfiguration gesendet werden sollen.

Parameter

Name	Typ	Default	Beschreibung
$handle Pflicht	CurlHandle		Ein gültiges cURL-Handle, das zuvor mit `curl_init()` erstellt wurde und dessen Optionen kopiert werden sollen.

Rückgabewert

Typ

CurlHandle|false

Beschreibung

Gibt im Erfolgsfall ein neues CurlHandle-Objekt zurück, das eine vollständige Kopie des übergebenen Handles darstellt. Bei einem Fehler wird false zurückgegeben.

Beispiele

Basis-Handle kopieren und für verschiedene URLs verwenden

<?php
// Basis-Handle mit gemeinsamen Einstellungen erstellen
$base = curl_init();
curl_setopt($base, CURLOPT_RETURNTRANSFER, true);
curl_setopt($base, CURLOPT_TIMEOUT, 10);
curl_setopt($base, CURLOPT_USERAGENT, 'MeinBot/1.0');
curl_setopt($base, CURLOPT_HTTPHEADER, ['Accept: application/json']);

// Handle für erste URL kopieren
$ch1 = curl_copy_handle($base);
curl_setopt($ch1, CURLOPT_URL, 'https://api.example.com/users');
$result1 = curl_exec($ch1);
curl_close($ch1);

// Handle für zweite URL kopieren
$ch2 = curl_copy_handle($base);
curl_setopt($ch2, CURLOPT_URL, 'https://api.example.com/products');
$result2 = curl_exec($ch2);
curl_close($ch2);

// Basis-Handle schließen
curl_close($base);

echo 'Benutzer: ' . $result1 . PHP_EOL;
echo 'Produkte: ' . $result2 . PHP_EOL;

Parallele Requests mit Multi-cURL und kopierten Handles

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

// Basis-Handle konfigurieren
$base = curl_init();
curl_setopt($base, CURLOPT_RETURNTRANSFER, true);
curl_setopt($base, CURLOPT_TIMEOUT, 15);
curl_setopt($base, CURLOPT_FOLLOWLOCATION, true);

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

foreach ($urls as $url) {
    $ch = curl_copy_handle($base);
    curl_setopt($ch, CURLOPT_URL, $url);
    curl_multi_add_handle($multi, $ch);
    $handles[] = $ch;
}

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

// Ergebnisse auslesen und Handles schließen
foreach ($handles as $ch) {
    echo curl_multi_getcontent($ch) . PHP_EOL;
    curl_multi_remove_handle($multi, $ch);
    curl_close($ch);
}

curl_multi_close($multi);
curl_close($base);

// Wichtig · Fallstricke

Ressourcenverwaltung: Jedes mit curl_copy_handle() erzeugte Handle belegt eigene Ressourcen. Vergisst man curl_close() für eines der Handles, entstehen Speicherlecks – insbesondere in Schleifen mit vielen Kopien.

Cookies: Cookie-Daten (Session-Cookies im Speicher) werden beim Kopieren nicht übertragen – nur die Optionen (z. B. der Pfad zur Cookie-Datei). Cookies, die während einer Session gesammelt wurden, stehen im kopierten Handle nicht automatisch zur Verfügung.

PHP 8.0: Ab PHP 8.0 ist der Rückgabetyp CurlHandle statt der älteren resource-Typen. Code, der is_resource() zur Prüfung nutzt, sollte auf $handle instanceof CurlHandle umgestellt werden.

Siehe auch

curl_init curl_setopt curl_setopt_array curl_close curl_multi_init curl_exec