Signatur
Beschreibung
curl_error() liefert eine menschenlesbare Fehlermeldung für den zuletzt aufgetretenen Fehler einer cURL-Session. Die Funktion ist das Gegenstück zu curl_errno(), das lediglich den numerischen Fehlercode zurückgibt. Beide Funktionen werden typischerweise nach einem fehlgeschlagenen curl_exec()-Aufruf eingesetzt, um den Grund des Fehlers zu ermitteln.
Gibt curl_exec() false zurück, sollte unmittelbar danach curl_error() aufgerufen werden, bevor weitere cURL-Operationen am selben Handle ausgeführt werden, da der interne Fehlerstatus bei nachfolgenden Aufrufen überschrieben werden kann.
Ein leerer String als Rückgabewert bedeutet, dass kein Fehler aufgetreten ist oder die Session noch nicht ausgeführt wurde. Für eine vollständige Fehlerdiagnose empfiehlt es sich, curl_errno() und curl_error() gemeinsam zu nutzen und die Ausgabe sicher zu protokollieren.
Ab PHP 8.0 erwartet die Funktion ein CurlHandle-Objekt anstelle einer Resource, wie sie in früheren PHP-Versionen verwendet wurde.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $handle Pflicht | CurlHandle | Ein von curl_init() zurückgegebenes cURL-Handle-Objekt (CurlHandle). |
Rückgabewert
'') zurückgegeben.Beispiele
Fehlerbehandlung nach fehlgeschlagenem HTTP-Request
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://nicht-existente-domain.example.com');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_TIMEOUT, 5);
$response = curl_exec($ch);
if ($response === false) {
$errno = curl_errno($ch);
$error = curl_error($ch);
echo "cURL-Fehler ($errno): $error" . PHP_EOL;
} else {
echo $response;
}
curl_close($ch);Fehlerprotokollierung in einer Wrapper-Funktion
<?php
function httpGet(string $url): string|false
{
$ch = curl_init();
curl_setopt_array($ch, [
CURLOPT_URL => $url,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 10,
CURLOPT_FOLLOWLOCATION => true,
]);
$response = curl_exec($ch);
if ($response === false) {
$message = sprintf(
'[cURL] Fehler %d beim Abruf von %s: %s',
curl_errno($ch),
$url,
curl_error($ch)
);
error_log($message);
curl_close($ch);
return false;
}
curl_close($ch);
return $response;
}
$result = httpGet('https://example.com');
if ($result !== false) {
echo 'Antwort erhalten, Länge: ' . strlen($result) . ' Bytes';
}// Wichtig · Fallstricke
Sicherheitshinweis: Fehlermeldungen von curl_error() können sensible Informationen wie interne Hostnamen, Pfade oder IP-Adressen enthalten. Diese Meldungen sollten niemals ungefiltert an den Endnutzer ausgegeben werden, sondern ausschließlich serverseitig protokolliert werden (z. B. via error_log()).
Ressourcen-Typ: Bis PHP 7.x wurde ein cURL-Handle als resource behandelt. Ab PHP 8.0 ist es ein CurlHandle-Objekt. Code, der is_resource() zur Prüfung nutzt, muss angepasst werden.
Timing: curl_error() immer unmittelbar nach curl_exec() aufrufen, bevor weitere Operationen am Handle durchgeführt werden, da der Fehlerstatus intern überschrieben werden kann.