getFile()

Introducción

getFile() es un método integrado de la clase Exception de PHP (y de todas las clases que la extienden, incluida Error). Cuando se lanza una excepción, PHP registra la ruta del archivo fuente en el que se ejecutó la sentencia throw. getFile() devuelve esa ruta para que puedas identificar con precisión dónde ocurrió el error — algo invaluable cuando un error asciende por muchas capas de código.

Esta página explica qué devuelve getFile(), en qué se diferencia de métodos relacionados, y cómo combinarlo con getLine() y getMessage() para construir registros de error legibles.

Sintaxis

public string Exception::getFile(): string

getFile() se declara como final en la clase base Exception, por lo que no puedes sobrescribirlo en tus propias subclases de excepción — el valor siempre lo establece PHP en el momento en que se construye el objeto.

Parámetros

getFile() no recibe parámetros.

Valor de retorno

Un string que contiene la ruta absoluta del archivo en el que se lanzó la excepción — por ejemplo /var/www/app/src/Order.php, no simplemente Order.php. Si solo quieres el nombre del archivo, envuelve el resultado en basename().

La ruta refleja dónde se creó el objeto de excepción (el sitio de throw/new), no dónde fue capturado. Esta distinción importa cuando se relanza una excepción entre distintos archivos.

Ejemplo básico

El siguiente ejemplo lanza una excepción e informa exactamente de dónde provino:

<?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";
}

Salida (la ruta depende de dónde esté el script):

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

Observa que getFile() reporta la línea 4 mediante getLine() — la línea del throw, no del catch.

Construir una línea de log legible

En aplicaciones reales la ruta del archivo suele ser larga, por lo que es habitual recortarla con basename() y ensamblar un único mensaje de log compacto:

<?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";
}

Salida:

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

Aunque la excepción fue capturada dentro del bloque try, getFile() y getLine() apuntan a la línea 5 — la sentencia throw dentro de processOrder().

Cuándo usarlo

• Registro y monitoreo. Combina getFile() con getLine() y getMessage() para escribir entradas de log que indiquen exactamente dónde buscar.
• Depuración de llamadas profundamente anidadas. Cuando una excepción asciende por varias funciones o archivos, getFile() te dice el origen real, no el lugar donde fue capturada.
• Páginas de error personalizadas (en desarrollo). Muestra el archivo y la línea en una pantalla de depuración — pero nunca expongas rutas absolutas del servidor a los usuarios finales en producción.

Para obtener una imagen completa del error, a menudo lo combinarás con getTrace() o getTraceAsString(), que muestran toda la pila de llamadas en lugar de una sola ubicación.

Métodos relacionados

Consulta getMessage(), getLine() y getCode() para cada uno de estos. Para entender cómo encaja todo el mecanismo, lee el capítulo sobre excepciones en PHP y la referencia de try/catch.

Conclusión

getFile() es una parte pequeña pero esencial del sistema de excepciones de PHP: responde a la pregunta "¿qué archivo lanzó esto?". Junto con getLine() y getMessage(), convierte un fallo vago en un informe preciso y accionable — la base de un buen registro de eventos y una depuración rápida.

Práctica