getMessage()

Introducción

El manejo de excepciones en PHP te permite separar el código que detecta un problema del código que responde a él. Cuando algo sale mal, puedes lanzar con throw un objeto de excepción que viaja por la pila de llamadas hasta que un bloque catch coincidente lo gestiona. Ese objeto contiene detalles sobre lo que ocurrió — y el más utilizado de esos detalles es el mensaje de error legible por humanos.

Este capítulo cubre Exception::getMessage(), el método que devuelve ese string de mensaje. Aprenderás qué devuelve, cómo se diferencia de los otros métodos "getter" del objeto de excepción, los errores comunes y cómo usarlo para errores orientados al usuario, registro y depuración.

Qué devuelve getMessage()

getMessage() devuelve el string de mensaje que se pasó como primer argumento al constructor de la excepción. PHP almacena ese string en el objeto de excepción en el momento en que se crea, y getMessage() simplemente lo lee de vuelta.

<?php
$e = new Exception("Something went wrong");
echo $e->getMessage(); // Something went wrong

Dos datos a recordar:

• No toma argumentos y siempre devuelve un string.
• Si no se pasó ningún mensaje al constructor, devuelve un string vacío (""), no null.

<?php
$e = new Exception();      // no message
var_dump($e->getMessage()); // string(0) ""

getMessage() está definido en la clase base Exception (y en Error), por lo que está disponible en todas las excepciones integradas y personalizadas — RuntimeException, InvalidArgumentException, TypeError, y cualquier clase que las extienda.

Sintaxis

final public Exception::getMessage(): string

El método es final, lo que significa que las subclases no pueden sobreescribirlo — el mensaje que pasas a new Exception("...") es exactamente lo que obtienes de vuelta.

Uso básico

Para leer un mensaje, captura la excepción en un bloque try/catch. El bloque try contiene el código que podría fallar; el bloque catch se ejecuta solo si se lanza una excepción con throw.

<?php

function divide($a, $b) {
    if ($b === 0) {
        throw new InvalidArgumentException("Cannot divide by zero.");
    }
    return $a / $b;
}

try {
    echo divide(10, 0);
} catch (Exception $e) {
    echo "Caught: " . $e->getMessage();
}
?>

Salida:

Caught: Cannot divide by zero.

InvalidArgumentException extiende Exception, por lo que el bloque catch (Exception $e) aún la captura, y getMessage() devuelve el string personalizado que pasamos al lanzar la excepción.

Casos de uso prácticos

Registro de errores

Un patrón común es escribir el mensaje en un registro para poder investigar fallos más tarde. Combina getMessage() con getCode(), getFile() y getLine() para entradas de registro más completas.

<?php
try {
    throw new RuntimeException("Database connection failed");
} catch (RuntimeException $e) {
    $entry = sprintf("[%s] %s", date("Y-m-d"), $e->getMessage());
    echo $entry;
}
?>

Salida (la fecha variará):

[2026-06-21] Database connection failed

Mostrar un mensaje seguro al usuario

Los mensajes de excepción suelen contener detalles técnicos. Usa getMessage() para tus registros, pero muestra a los usuarios un mensaje genérico en producción para no filtrar información interna como rutas de archivos o SQL.

<?php
try {
    throw new Exception("SQLSTATE[28000]: Invalid password for user 'root'");
} catch (Exception $e) {
    error_log($e->getMessage());          // full detail goes to the log
    echo "Sorry, something went wrong.";  // safe message for the user
}
?>

getMessage() vs. los otros getters de excepción

getMessage() es uno de varios métodos de solo lectura en un objeto de excepción. Saber qué devuelve cada uno te ayuda a elegir el correcto:

Si quieres todo de una vez para depuración, convertir la excepción a string (mediante __toString()) proporciona un volcado formateado que ya incluye el mensaje, archivo, línea y traza.

Errores comunes

• Mensaje vacío, no null. Como se mostró anteriormente, una excepción sin mensaje devuelve "". Código como if ($e->getMessage()) lo tratará como falso — prevé esto si un mensaje vacío es significativo en tu dominio.
• getMessage() es final. No puedes sobreescribirlo para transformar el texto. Para personalizar lo que ven los llamadores, pasa el string deseado al constructor (frecuentemente mediante parent::__construct($message) en una clase de excepción personalizada).
• fopen() no lanza excepciones por defecto. Muchas funciones PHP emiten advertencias y devuelven false en lugar de lanzar excepciones. En el ejemplo de archivo a continuación verificamos el valor de retorno y lanzamos manualmente; funciones como estas no poblarán getMessage() por sí solas a menos que conviertas la advertencia en una excepción (por ejemplo con set_error_handler()).

Ejemplo completo

<?php

try {
    // fopen() returns false and emits a warning on failure rather than throwing
    $file = @fopen("does-not-exist.txt", "r");
    if (!$file) {
        throw new Exception("File not found");
    }
} catch (Exception $e) {
    echo "Error message: " . $e->getMessage();
}
?>

Salida:

Error message: File not found

Aquí abrimos un archivo, detectamos el fallo comprobando el valor de retorno de fopen(), y lanzamos una Exception con un mensaje personalizado. getMessage() luego recupera ese string para que podamos mostrarlo o registrarlo. Para una limpieza garantizada independientemente del éxito o fracaso, añadirías un bloque finally.

Conclusión

Exception::getMessage() devuelve el mensaje de error almacenado en una excepción capturada — el string que pasaste al constructor, o un string vacío si no se proporcionó ninguno. Es el getter de excepción más simple y más utilizado, ideal para registro, depuración y generación de retroalimentación orientada al usuario. Combínalo con los otros getters como getCode() y getTrace() para informes de error completos, y revisa el modelo general de manejo de excepciones de PHP para usarlo de manera efectiva.

Práctica