getCode()

Die PHP getCode()-Methode

Wenn Sie in PHP eine Exception abfangen, müssen Sie häufig wissen, welcher Fehler aufgetreten ist, um unterschiedlich darauf reagieren zu können. Die Methode Exception::getCode() liefert genau das: Sie gibt den Integer-Fehlercode zurück, der der Exception bei ihrer Erstellung mitgegeben wurde. Diese Seite erklärt, was der Code ist, wie man ihn setzt und ausliest, wie er sich in der Standard-Exception-Hierarchie verhält und welche Fallstricke es gibt.

Wenn Sie neu im Bereich Fehlerbehandlung sind, lesen Sie zunächst PHP-Exceptions und die try-catch-Anweisung, bevor Sie hierher zurückkehren.

Was der Exception-Code ist

Jedes PHP-Exception-Objekt enthält drei grundlegende Informationen: eine Nachricht (ausgelesen mit getMessage()), eine Zeile/Datei (ausgelesen mit getLine()) und einen Code. Der Code ist ein vom Entwickler definierter Wert, den Sie als zweites Argument an den Exception-Konstruktor übergeben:

new Exception(string $message = "", int $code = 0, ?Throwable $previous = null)

getCode() gibt schlicht dieses zweite Argument zurück. Es ist ein Label, das Sie wählen – PHP befüllt es nicht automatisch. Wenn Sie keinen Code übergeben, ist der Standardwert 0.

Syntax

public Exception::getCode(): mixed

• Parameter: keine.
• Rückgabewert: der an den Konstruktor übergebene Code. Für die Basisklasse Exception ist dies ein int (Standard 0).

Hinweis: Der Rückgabetyp ist als mixed dokumentiert, da ErrorException und einige PDO-Exceptions string-Codes verwenden (zum Beispiel SQLSTATE-Werte). Bei einer einfachen Exception ist ein Integer zu erwarten.

Einfaches Beispiel

Hier wird eine Exception mit dem Code 100 geworfen und dann im catch-Block ausgelesen:

<?php

try {
    throw new Exception("Database connection failed", 100);
} catch (Exception $e) {
    echo "Message: " . $e->getMessage() . "\n";
    echo "Code: " . $e->getCode() . "\n";
}

Ausgabe:

Message: Database connection failed
Code: 100

getCode() gibt 100 zurück – den übergebenen Wert – während getMessage() den Text zurückgibt. Beide sind unabhängig voneinander.

Verzweigung anhand des Codes

Der eigentliche Zweck eines Codes besteht darin, einem einzigen catch-Block zu ermöglichen, verschiedene Fehler an unterschiedliche Handler weiterzuleiten. Die folgenden Codes sind beliebige Konstanten, die für die Anwendung gewählt wurden:

<?php

const ERR_DB        = 100;
const ERR_NOT_FOUND = 404;

function loadUser(int $id): string
{
    if ($id < 1) {
        throw new Exception("Invalid user id", ERR_NOT_FOUND);
    }
    // ...imagine a DB lookup that fails...
    throw new Exception("Could not reach the database", ERR_DB);
}

try {
    echo loadUser(0);
} catch (Exception $e) {
    switch ($e->getCode()) {
        case ERR_NOT_FOUND:
            echo "404: " . $e->getMessage();
            break;
        case ERR_DB:
            echo "500: " . $e->getMessage();
            break;
        default:
            echo "Unknown error: " . $e->getMessage();
    }
}

Ausgabe:

404: Invalid user id

Da wir loadUser(0) aufgerufen haben, greift zuerst die Prüfung $id < 1 und wirft eine Exception mit ERR_NOT_FOUND (404), sodass dieser case ausgeführt wird.

Der Standardcode ist 0

Wenn Sie eine Exception ohne Code erstellen, gibt getCode() 0 zurück, nicht null:

<?php

try {
    throw new Exception("Something went wrong");
} catch (Exception $e) {
    var_dump($e->getCode());
}

Ausgabe:

int(0)

Das ist wichtig bei der Verzweigung anhand des Codes: if ($e->getCode()) behandelt einen fehlenden Code (0) als falsy, was in der Regel gewünscht ist – seien Sie jedoch bewusst damit.

Eigene Exception-Klassen

Ein verbreitetes Muster besteht darin, den Code in eine dedizierte Exception-Klasse einzubetten, sodass Aufrufer die magische Zahl nie selbst angeben müssen:

<?php

class HttpException extends Exception {}

class NotFoundException extends HttpException
{
    public function __construct(string $message = "Not Found")
    {
        parent::__construct($message, 404);
    }
}

try {
    throw new NotFoundException("User profile not found");
} catch (HttpException $e) {
    echo $e->getCode() . " " . $e->getMessage();
}

Ausgabe:

404 User profile not found

Der Konstruktor von NotFoundException leitet 404 an parent::__construct() weiter, sodass getCode() 404 zurückgibt, obwohl der aufrufende Code diese Zahl nie explizit angegeben hat.

getCode() vs. getMessage() vs. getPrevious()

Diese Methoden ergänzen sich gegenseitig – die meisten realen Handler lesen alle drei aus.

Häufige Fallstricke

• Der Code muss für Exception ein Integer sein. Das Übergeben eines string (z. B. new Exception("x", "ABC")) wirft in modernem PHP einen TypeError. Verwenden Sie stattdessen eine Konstante.
• getCode() ist nicht der HTTP-Statuscode. Es ist nur dann ein Statuscode, wenn Sie sich dafür entschieden haben, einen dort zu speichern. PHP tut selbst nichts mit dem Wert.
• Eingebaute Exceptions setzen selten einen sinnvollen Code. Die meisten PHP-Core-Exceptions lassen ihn bei 0; verlassen Sie sich nicht darauf, dass er befüllt ist, wenn Sie ihn nicht selbst gesetzt haben.
• PDOException-Codes sind SQLSTATE-strings. Beim Abfangen von Datenbankfehlern kann getCode() etwas wie "42S02" (einen string) zurückgeben, weshalb der Rückgabetyp mixed ist.

Best Practices

1. Definieren Sie benannte Konstanten (oder klassenbasierte Exceptions) für Codes, anstatt rohe Zahlen zu verstreuen.
2. Halten Sie Codes stabil – anderer Code und Protokolle können von ihnen abhängen.
3. Protokollieren Sie den Code zusammen mit getMessage() und getLine(), damit Fehler nachvollziehbar sind.
4. Stellen Sie interne Codes oder Meldungen nicht Endbenutzern zur Verfügung; ordnen Sie sie sicheren, generischen Antworten zu.

Fazit

Exception::getCode() gibt den Integer-Code zurück, den Sie beim Erstellen der Exception angehängt haben, und bietet Ihnen eine zuverlässige, maschinenlesbare Möglichkeit, einen Fehler von einem anderen zu unterscheiden. Kombinieren Sie ihn mit getMessage() für menschenlesbare Details, bevorzugen Sie benannte Konstanten oder eigene Exception-Klassen gegenüber magischen Zahlen, und denken Sie daran, dass einige Exception-Typen (wie PDOException) string-Codes verwenden.

Übungen