getFile()

Introduction

getFile() est une méthode intégrée de la classe Exception de PHP (et de toute classe qui l'étend, y compris Error). Lorsqu'une exception est levée, PHP enregistre le chemin du fichier source dans lequel l'instruction throw a été exécutée. getFile() retourne ce chemin afin que vous puissiez identifier précisément où quelque chose a mal tourné — ce qui est précieux lorsqu'une erreur remonte à travers de nombreuses couches de code.

Cette page explique ce que retourne getFile(), en quoi elle diffère des méthodes apparentées, et comment la combiner avec getLine() et getMessage() pour construire des journaux d'erreurs lisibles.

Syntaxe

public string Exception::getFile(): string

getFile() est déclarée final sur la classe de base Exception, vous ne pouvez donc pas la redéfinir dans vos propres sous-classes d'exception — la valeur est toujours définie par PHP lui-même au moment où l'objet est construit.

Paramètres

getFile() ne prend aucun paramètre.

Valeur de retour

Une string contenant le chemin absolu du fichier dans lequel l'exception a été levée — par exemple /var/www/app/src/Order.php, et non simplement Order.php. Si vous ne voulez que le nom du fichier, encapsulez le résultat dans basename().

Le chemin reflète l'endroit où l'objet exception a été créé (le site throw/new), et non l'endroit où il a été attrapé. Cette distinction est importante lorsque vous relancez des exceptions entre différents fichiers.

Exemple de base

L'exemple ci-dessous lève une exception, puis indique exactement d'où elle provient :

<?php

try {
    throw new Exception('Database connection failed');
} catch (Exception $e) {
    echo 'Message: ', $e->getMessage(), "\n";
    echo 'File: ', $e->getFile(), "\n";
    echo 'Line: ', $e->getLine(), "\n";
}

Sortie (le chemin dépend de l'emplacement du script) :

Message: Database connection failed
File: /var/www/app/index.php
Line: 4

Notez que getFile() signale la ligne 4 via getLine() — la ligne du throw, et non du catch.

Construire une ligne de journal lisible

Dans les applications réelles, le chemin de fichier est généralement long, il est donc courant de le raccourcir avec basename() et d'assembler un message de journal unique et compact :

<?php

function processOrder(int $id): void
{
    throw new RuntimeException("Order #$id is invalid");
}

try {
    processOrder(42);
} catch (RuntimeException $e) {
    echo 'Error in ' . basename($e->getFile())
        . ' (line ' . $e->getLine() . '): '
        . $e->getMessage() . "\n";
}

Sortie :

Error in index.php (line 5): Order #42 is invalid

Même si l'exception a été attrapée à l'intérieur du bloc try, getFile() et getLine() pointent vers la ligne 5 — l'instruction throw à l'intérieur de processOrder().

Quand l'utiliser

• Journalisation et surveillance. Combinez getFile() avec getLine() et getMessage() pour écrire des entrées de journal indiquant exactement où chercher.
• Débogage d'appels profondément imbriqués. Lorsqu'une exception remonte à travers plusieurs fonctions ou fichiers, getFile() vous indique la véritable origine, et non l'endroit où elle a été attrapée.
• Pages d'erreur personnalisées (en développement). Affichez le fichier et la ligne sur un écran de débogage — mais n'exposez jamais les chemins absolus du serveur aux utilisateurs finaux en production.

Pour avoir une vue complète d'une erreur, vous l'associerez souvent à getTrace() ou getTraceAsString(), qui affichent la pile d'appels complète plutôt qu'un seul emplacement.

Méthodes associées

Consultez getMessage(), getLine() et getCode() pour chacune de ces méthodes. Pour comprendre comment l'ensemble du mécanisme s'articule, lisez le chapitre sur les exceptions PHP et la référence try/catch.

Conclusion

getFile() est une partie petite mais essentielle du système d'exceptions de PHP : elle répond à la question « quel fichier a levé cette exception ? ». Associée à getLine() et getMessage(), elle transforme un échec vague en un rapport précis et exploitable — la base d'une bonne journalisation et d'un débogage rapide.

Pratique