Die Methode Exception::getLine() in PHP verstehen

Wenn in PHP etwas schiefläuft, müssen Sie meist zuerst wissen, wo der Fehler aufgetreten ist. Die Methode Exception::getLine() beantwortet genau das: Sie liefert die Zeilennummer, in der ein Ausnahmeobjekt erstellt wurde. In Kombination mit getMessage() und getFile() erhalten Sie ein präzises „Was und Wo" für jeden abgefangenen Fehler — die Grundlage für nützliches Logging und Debugging.

Diese Seite behandelt die Signatur der Methode, was sie tatsächlich misst, ein vollständiges ausführbares Beispiel sowie häufige Fallstricke.

Syntax

final public Exception::getLine(): int

Die Methode erwartet keine Argumente und gibt einen int zurück. Sie ist auf der Basisklasse Exception definiert, sodass alle eingebauten Ausnahmen (RuntimeException, InvalidArgumentException, TypeError usw.) und alle eigenen Ausnahmen, die Sie schreiben, sie erben. Da sie als final deklariert ist, kann sie in einer Unterklasse nicht überschrieben werden.

Was „Zeile" tatsächlich bedeutet

Dies ist das Wichtigste, das Sie verstehen müssen: getLine() gibt die Zeile zurück, in der das Ausnahmeobjekt konstruiert wurde (die new Exception(...) / throw new ...-Stelle) — nicht die Zeile des eigentlichen Problems und nicht die Zeile, in der es abgefangen wurde.

Wenn Ihr Code also eine Funktion aufruft, die intern wirft, zeigt getLine() auf die throw-Anweisung innerhalb dieser Funktion — nicht auf Ihren Aufruf. Um den vollständigen Pfad von Ihrem Aufruf bis zum throw zu verfolgen, verwenden Sie stattdessen getTrace() oder getTraceAsString().

Ein vollständiges, ausführbares Beispiel

Das folgende Beispiel definiert eine Funktion, die eine Ausnahme wirft, wenn eine Datei fehlt, fängt diese dann ab und gibt den Ort aus:

<?php

function readFileContents(string $path): string
{
    if (!file_exists($path)) {
        throw new Exception("File not found: $path"); // this is line 6
    }

    return file_get_contents($path);
}

try {
    echo readFileContents('/no/such/file.txt');
} catch (Exception $e) {
    echo "Error on line " . $e->getLine() . ": " . $e->getMessage();
}

Ausgabe:

Error on line 6: File not found: /no/such/file.txt

Beachten Sie, dass die gemeldete Zeile 6 ist — die throw-Anweisung innerhalb von readFileContents() — obwohl der Aufruf, der sie ausgelöst hat, in Zeile 13 steht. Das ist die Regel „Konstruktionsort, nicht Aufrufstelle" in der Praxis.

getLine() mit getFile() kombinieren

Eine Zeilennummer allein ist in einem Mehrprojekt-Datei-Projekt mehrdeutig. Im echten Code geben Sie sie daher fast immer zusammen mit dem Dateinamen aus getFile() aus:

<?php

try {
    $age = -5;

    if ($age < 0) {
        throw new InvalidArgumentException("Age cannot be negative");
    }
} catch (Exception $e) {
    printf(
        "[%s] %s (line %d in %s)\n",
        get_class($e),
        $e->getMessage(),
        $e->getLine(),
        basename($e->getFile())
    );
}

Ausgabe (der Dateiname hängt davon ab, wie Sie das Skript benennen):

[InvalidArgumentException] Age cannot be negative (line 5 in script.php)

Hier gibt getLine() 5 zurück — die Zeile des throw innerhalb des try-Blocks. Das Abfangen mit Exception funktioniert für InvalidArgumentException, weil jeder Ausnahmetyp letztendlich Exception erweitert.

Wann man es verwendet

• Logging. Schreiben Sie getLine() und getFile() in Ihre Log-Einträge, damit eine Nachricht ohne Stack-Trace noch nachverfolgbar ist.
• Benutzerdefinierte Fehlerseiten. In einer Entwicklungsumgebung können Sie die Zeile dem Entwickler anzeigen; in der Produktion protokollieren Sie sie, zeigen dem Benutzer aber eine allgemeine Meldung.
• Ausnahmen neu verpacken. Wenn Sie eine Low-Level-Ausnahme abfangen und eine domänenspezifische neu werfen, zeichnen Sie das originale getLine()/getFile() auf (oder verketten Sie mit getPrevious()), damit die Grundursache nicht verloren geht.

Häufige Fallstricke

• Die Aufrufstelle erwarten. Wie oben gezeigt, ist getLine() der Ort des throw, nicht der Ort, an dem Sie den werfenden Code aufgerufen haben. Verwenden Sie einen Trace für den vollständigen Pfad.
• Es ohne Abfangen lesen. getLine() ist eine Instanzmethode — Sie können sie nur auf einem Ausnahmeobjekt aufrufen, auf das Sie eine Referenz haben, typischerweise das $e aus einem catch-Block.
• Verwechslung mit getCode(). getCode() gibt den numerischen Code der Ausnahme zurück — einen unabhängigen Wert, den Sie beim Konstruieren der Ausnahme setzen; er hat nichts mit Zeilennummern zu tun.

Fazit

Exception::getLine() gibt die ganzzahlige Zeilennummer zurück, in der eine Ausnahme erstellt wurde — eine kleine, aber wesentliche Debugging-Information. Zusammen mit getMessage(), getFile() und einem vollständigen Stack-Trace können Sie Fehler präzise bestimmen und protokollieren. Für das größere Bild zum Werfen und Abfangen von Ausnahmen lesen Sie den Leitfaden zu PHP-Ausnahmen.

Übungen