Comprendre la méthode Exception::getLine() en PHP

Lorsque quelque chose tourne mal en PHP, la première chose dont vous avez généralement besoin est de savoir où cela s'est produit. La méthode Exception::getLine() répond exactement à cette question : elle vous indique le numéro de ligne sur lequel un objet exception a été créé. Associée à getMessage() et getFile(), elle vous fournit un « quoi, où » précis pour chaque erreur que vous interceptez — ce qui constitue la base d'une journalisation et d'un débogage efficaces.

Cette page couvre la signature de la méthode, ce qu'elle mesure réellement, un exemple complet exécutable et les pièges courants qui font trébucher les développeurs.

Syntaxe

final public Exception::getLine(): int

La méthode ne prend aucun argument et retourne un int. Elle est définie sur la classe de base Exception, donc chaque exception intégrée (RuntimeException, InvalidArgumentException, TypeError, etc.) et chaque exception personnalisée que vous écrivez l'hérite. Comme elle est déclarée final, vous ne pouvez pas la redéfinir dans une sous-classe.

Ce que « ligne » signifie réellement

C'est la chose la plus importante à comprendre : getLine() retourne la ligne où l'objet exception a été construit (l'emplacement du new Exception(...) / throw new ...), pas la ligne du problème sous-jacent et pas la ligne où il a été intercepté.

Donc si votre code appelle une fonction qui lève une exception en interne, getLine() pointe vers l'instruction throw à l'intérieur de cette fonction — pas vers votre appel. Pour retracer le chemin complet de votre appel jusqu'au throw, utilisez getTrace() ou getTraceAsString() à la place.

Un exemple complet et exécutable

L'exemple ci-dessous définit une fonction qui lève une exception quand un fichier est manquant, puis intercepte l'exception et signale l'emplacement :

<?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();
}

Résultat :

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

Notez que la ligne indiquée est 6 — l'instruction throw à l'intérieur de readFileContents() — même si l'appel qui l'a déclenchée se trouve à la ligne 13. C'est la règle « emplacement de construction, pas emplacement d'appel » en action.

Combiner getLine() avec getFile()

Un numéro de ligne seul est ambigu dans un projet multi-fichiers, donc dans du code réel, vous l'affichez presque toujours avec le nom de fichier fourni par getFile() :

<?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())
    );
}

Résultat (le nom du fichier dépend du nom que vous donnez au script) :

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

Ici getLine() retourne 5, la ligne du throw à l'intérieur du bloc try. Intercepter Exception fonctionne pour InvalidArgumentException car chaque type d'exception étend finalement Exception.

Quand l'utiliser

• Journalisation. Écrivez getLine() et getFile() dans vos entrées de journal pour qu'un message sans trace de pile soit encore traçable.
• Pages d'erreur personnalisées. Dans un environnement de développement, vous pouvez afficher la ligne au développeur ; en production, journalisez-la mais montrez à l'utilisateur un message générique.
• Re-encapsulation d'exceptions. Lorsque vous interceptez une exception de bas niveau et relancez une exception spécifique au domaine, enregistrez le getLine()/getFile() original (ou chaînez avec getPrevious()) pour ne pas perdre la cause racine.

Pièges courants

• S'attendre à l'emplacement d'appel. Comme indiqué ci-dessus, getLine() est l'emplacement du throw, pas là où vous avez appelé le code qui lève l'exception. Utilisez une trace pour le chemin complet.
• L'appeler sans interception. getLine() est une méthode d'instance — vous pouvez seulement l'appeler sur un objet exception dont vous avez une référence, généralement le $e d'un bloc catch.
• La confondre avec getCode(). getCode() retourne le code numérique de l'exception, une valeur sans rapport que vous définissez lors de la construction de l'exception ; elle n'a rien à voir avec les numéros de ligne.

Conclusion

Exception::getLine() retourne le numéro de ligne entier où une exception a été créée — une information de débogage petite mais essentielle. Utilisée avec getMessage(), getFile() et une trace de pile complète, elle vous permet de localiser et de journaliser les erreurs avec précision. Pour avoir une vue d'ensemble de la levée et de l'interception d'exceptions, consultez le guide sur les exceptions PHP.

Pratique