Signatur
Beschreibung
CurlHandle ist eine vollständig opake Klasse, deren Instanzen ausschließlich von PHP-internen cURL-Funktionen erzeugt und verwaltet werden. Anwender können keine eigenen Instanzen dieser Klasse erstellen; stattdessen wird eine Instanz durch den Aufruf von curl_init() zurückgegeben. Das Handle wird dann an alle weiteren cURL-Funktionen wie curl_setopt(), curl_exec() oder curl_close() übergeben.
Vor PHP 8.0.0 arbeiteten cURL-Funktionen mit dem generischen Typ resource. Der Wechsel zu CurlHandle ermöglicht eine stärkere Typsicherheit: Type-Hints in Funktions-Signaturen können nun präzise auf CurlHandle lauten, und PHP kann zur Laufzeit prüfen, ob tatsächlich ein gültiges cURL-Handle übergeben wird. Fehlerhafte Übergaben werden so frühzeitig erkannt.
Da die Klasse vollständig opak ist, hat sie keine öffentlichen Eigenschaften oder Methoden, die direkt aufgerufen werden könnten. Die gesamte Interaktion erfolgt über die prozeduralen cURL-Funktionen der PHP-Standardbibliothek. Das Handle wird automatisch freigegeben, wenn es den Scope verlässt oder curl_close() aufgerufen wird – ab PHP 8.0.0 ist curl_close() jedoch ein No-Op, da der Garbage Collector die Freigabe übernimmt.
Für parallele HTTP-Anfragen existiert die verwandte Klasse CurlMultiHandle (zurückgegeben von curl_multi_init()) sowie CurlShareHandle (zurückgegeben von curl_share_init()).
Beispiele
Einfacher GET-Request mit CurlHandle und Type-Hint
<?php
function fetchUrl(CurlHandle $ch): string|false
{
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
return curl_exec($ch);
}
$ch = curl_init('https://example.com');
if ($ch === false) {
throw new RuntimeException('curl_init() fehlgeschlagen');
}
$response = fetchUrl($ch);
if ($response === false) {
echo 'Fehler: ' . curl_error($ch);
} else {
echo 'HTTP-Status: ' . curl_getinfo($ch, CURLINFO_HTTP_CODE) . PHP_EOL;
echo 'Bytes empfangen: ' . strlen($response) . PHP_EOL;
}
// Ab PHP 8.0 optional; GC gibt das Handle frei
curl_close($ch);POST-Request mit JSON-Body und Timeout
<?php
$payload = json_encode(['name' => 'PHP', 'version' => '8.4']);
$ch = curl_init('https://httpbin.org/post');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => $payload,
CURLOPT_TIMEOUT => 10,
CURLOPT_HTTPHEADER => [
'Content-Type: application/json',
'Content-Length: ' . strlen($payload),
],
]);
$result = curl_exec($ch);
$info = curl_getinfo($ch);
echo 'Statuscode: ' . $info['http_code'] . PHP_EOL;
echo 'Gesamtzeit: ' . $info['total_time'] . 's' . PHP_EOL;
if (curl_errno($ch) !== 0) {
echo 'cURL-Fehler: ' . curl_error($ch);
}// Wichtig · Fallstricke
Sicherheit: Beim Abrufen externer URLs immer CURLOPT_SSL_VERIFYPEER und CURLOPT_SSL_VERIFYHOST auf true belassen (Standardwerte). Das Deaktivieren dieser Optionen öffnet die Anwendung für Man-in-the-Middle-Angriffe.
Migration von PHP 7: Code, der mit is_resource($ch) prüft, ob ein Handle gültig ist, schlägt unter PHP 8 fehl. Verwende stattdessen $ch instanceof CurlHandle oder prüfe auf !== false direkt nach curl_init().
Kein Klonen: CurlHandle-Instanzen können nicht geklont werden. Für eine Kopie eines bestehenden Handles steht curl_copy_handle() zur Verfügung.
curl_close(): Ab PHP 8.0 ist der Aufruf von curl_close() nicht mehr notwendig und hat keinen Effekt, schadet aber auch nicht. Der Garbage Collector schließt das Handle automatisch.