getMessage()

Введение

Обработка исключений в PHP позволяет отделить код, который обнаруживает проблему, от кода, который на неё реагирует. Когда что-то идёт не так, вы throw объект исключения, который перемещается вверх по стеку вызовов до тех пор, пока подходящий блок catch не перехватит его. Этот объект содержит сведения о произошедшем — и наиболее часто используемое из них — удобочитаемое сообщение об ошибке.

В этой главе рассматривается Exception::getMessage() — метод, возвращающий эту строку сообщения. Вы узнаете, что он возвращает, чем отличается от других методов-«геттеров» объекта исключения, о типичных подводных камнях, а также о том, как использовать его для пользовательских сообщений, логирования и отладки.

Что возвращает getMessage()

getMessage() возвращает строку сообщения, переданную в качестве первого аргумента конструктору исключения. PHP сохраняет эту строку в объекте исключения в момент его создания, а getMessage() просто считывает её обратно.

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

Два факта, которые стоит запомнить:

• Метод не принимает аргументов и всегда возвращает string.
• Если конструктору не было передано сообщение, он возвращает пустую строку (""), а не null.

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

getMessage() определён в базовом классе Exception (и в Error), поэтому он доступен для каждого встроенного и пользовательского исключения — RuntimeException, InvalidArgumentException, TypeError и любого класса, расширяющего их.

Синтаксис

final public Exception::getMessage(): string

Метод является final, что означает: подклассы не могут его переопределить — сообщение, переданное в new Exception("..."), будет возвращено именно таким.

Базовое использование

Чтобы прочитать сообщение, перехватите исключение в блоке try/catch. Блок try содержит код, который может завершиться ошибкой; блок catch выполняется только при возникновении исключения.

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

Вывод:

Caught: Cannot divide by zero.

InvalidArgumentException расширяет Exception, поэтому блок catch (Exception $e) всё равно его перехватит, а getMessage() вернёт пользовательскую строку, переданную при выбросе исключения.

Практические примеры использования

Логирование ошибок

Распространённый шаблон — запись сообщения в лог для последующего анализа сбоев. Сочетайте getMessage() с getCode(), getFile() и getLine() для более подробных записей в логе.

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

Вывод (дата будет различаться):

[2026-06-21] Database connection failed

Показ безопасного сообщения пользователю

Сообщения исключений нередко содержат технические подробности. Используйте getMessage() для логов, но в продакшене показывайте пользователям общее сообщение, чтобы не раскрывать внутренние детали — пути к файлам или 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() против других геттеров исключений

getMessage() — один из нескольких методов только для чтения объекта исключения. Понимание того, что возвращает каждый из них, поможет выбрать нужный:

Если для отладки нужно всё сразу, приведение исключения к строке (через __toString()) даёт форматированный дамп, уже включающий сообщение, файл, строку и трассировку.

Подводные камни

• Пустая строка, не null. Как показано выше, исключение без сообщения возвращает "". Код вида if ($e->getMessage()) воспримет это как ложное значение — учитывайте это, если пустое сообщение имеет смысл в вашей предметной области.
• getMessage() является final. Вы не можете переопределить его для преобразования текста. Чтобы настроить то, что видят вызывающие, передайте нужную строку конструктору (как правило, через parent::__construct($message) в пользовательском классе исключения).
• fopen() по умолчанию не выбрасывает исключений. Многие PHP-функции генерируют предупреждения и возвращают false вместо того, чтобы бросать исключения. В приведённом ниже примере с файлом мы проверяем возвращаемое значение и бросаем исключение вручную; такие функции не заполнят getMessage() сами по себе, если только вы не преобразуете предупреждение в исключение (например, с помощью set_error_handler()).

Полный пример

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

Вывод:

Error message: File not found

Здесь мы открываем файл, обнаруживаем сбой, проверяя возвращаемое значение fopen(), и бросаем Exception с пользовательским сообщением. getMessage() затем извлекает эту строку, чтобы мы могли отобразить или записать её в лог. Для гарантированной очистки независимо от успеха или неудачи следует добавить блок finally.

Заключение

Exception::getMessage() возвращает сообщение об ошибке, хранящееся в перехваченном исключении — строку, переданную конструктору, или пустую строку, если сообщение не указано. Это простейший и наиболее используемый геттер исключений, идеально подходящий для логирования, отладки и формирования пользовательских сообщений. Комбинируйте его с другими геттерами, такими как getCode() и getTrace(), для создания полных отчётов об ошибках, и изучите общую модель обработки исключений в PHP для его эффективного использования.

Практика