curl_errno — Funktion · PHP-Referenz

Signatur

curl_errno(CurlHandle $handle): int

Beschreibung

curl_errno() liefert den numerischen Fehlercode des zuletzt aufgetretenen cURL-Fehlers für ein bestimmtes cURL-Handle. Der Rückgabewert ist 0, wenn kein Fehler aufgetreten ist, oder eine positive Ganzzahl, die dem entsprechenden cURL-Fehlercode (CURLE_*-Konstante) entspricht.

Die Funktion wird typischerweise nach curl_exec() aufgerufen, um zu prüfen, ob die Anfrage erfolgreich war. In Kombination mit curl_error(), das eine lesbare Fehlermeldung zurückgibt, lässt sich eine aussagekräftige Fehlerbehandlung implementieren.

Nützliche Fehlercodes sind beispielsweise CURLE_COULDNT_CONNECT (7) für Verbindungsfehler, CURLE_OPERATION_TIMEDOUT (28) für Timeouts oder CURLE_SSL_CACERT (60) für SSL-Zertifikatsprobleme. Eine vollständige Liste der cURL-Fehlercodes ist in der libcurl-Dokumentation zu finden.

Seit PHP 8.0 erwartet die Funktion ein CurlHandle-Objekt anstelle einer Ressource. In PHP 7 und früher wurde ein Ressource-Typ verwendet, der intern noch unterstützt wird.

Parameter

Name	Typ	Default	Beschreibung
$handle Pflicht	CurlHandle		Ein von `curl_init()` zurückgegebenes cURL-Handle-Objekt.

Rückgabewert

Typ

int

Beschreibung

Gibt 0 zurück, wenn kein Fehler aufgetreten ist, oder eine positive Ganzzahl mit dem entsprechenden cURL-Fehlercode, falls ein Fehler vorliegt.

Beispiele

Grundlegende Fehlerbehandlung nach curl_exec()

<?php
$ch = curl_init('https://www.example.com/api/data');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_TIMEOUT, 10);

$response = curl_exec($ch);

if (curl_errno($ch) !== 0) {
    $errorCode    = curl_errno($ch);
    $errorMessage = curl_error($ch);
    echo "cURL-Fehler [{$errorCode}]: {$errorMessage}" . PHP_EOL;
} else {
    echo "Antwort erhalten: " . strlen($response) . " Bytes" . PHP_EOL;
}

curl_close($ch);

Antwort erhalten: 1256 Bytes

Gezieltes Reagieren auf bestimmte Fehlercodes

<?php
$ch = curl_init('https://unreachable.example.invalid/');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, 5);
curl_setopt($ch, CURLOPT_TIMEOUT, 10);

$response = curl_exec($ch);
$errno    = curl_errno($ch);

switch ($errno) {
    case 0:
        echo "Anfrage erfolgreich." . PHP_EOL;
        break;
    case CURLE_COULDNT_CONNECT: // 7
        echo "Verbindung konnte nicht hergestellt werden." . PHP_EOL;
        break;
    case CURLE_OPERATION_TIMEDOUT: // 28
        echo "Timeout: Die Anfrage hat zu lange gedauert." . PHP_EOL;
        break;
    case CURLE_SSL_CACERT: // 60
        echo "SSL-Zertifikat konnte nicht verifiziert werden." . PHP_EOL;
        break;
    default:
        echo "Unbekannter cURL-Fehler [{$errno}]: " . curl_error($ch) . PHP_EOL;
}

curl_close($ch);

Verbindung konnte nicht hergestellt werden.

// Wichtig · Fallstricke

Fehlerstatus wird nicht automatisch zurückgesetzt: Nach einem curl_reset() wird der Fehlerstatus geleert. Ohne Reset bleibt der letzte Fehlercode im Handle erhalten und kann bei mehrfacher Nutzung desselben Handles zu Verwirrung führen. Es empfiehlt sich daher, curl_errno() immer direkt nach curl_exec() aufzurufen.

Rückgabewert von curl_exec() prüfen: curl_exec() gibt bei einem Fehler false zurück. Ein HTTP-Statuscode wie 404 oder 500 gilt cURL-intern als erfolgreiche Übertragung (Fehlernummer 0). Für HTTP-Statuscodes sollte zusätzlich curl_getinfo($ch, CURLINFO_HTTP_CODE) verwendet werden.

PHP 8.0: Das Handle ist nun vom Typ CurlHandle; der frühere Ressource-Typ ist nicht mehr gültig.

Siehe auch

curl_error curl_exec curl_init curl_getinfo curl_reset