getMessage()

Introdução

O tratamento de exceções do PHP permite separar o código que detecta um problema do código que responde a ele. Quando algo dá errado, você lança (throw) um objeto de exceção que percorre a pilha de chamadas até que um bloco catch correspondente o trate. Esse objeto carrega detalhes sobre o que aconteceu — e o mais utilizado desses detalhes é a mensagem de erro legível por humanos.

Este capítulo aborda Exception::getMessage(), o método que retorna essa string de mensagem. Você aprenderá o que ele retorna, como difere dos outros métodos "getter" no objeto de exceção, armadilhas comuns e como usá-lo para erros voltados ao usuário, registro de logs e depuração.

O que getMessage() retorna

getMessage() retorna a string de mensagem que foi passada como primeiro argumento para o construtor da exceção. O PHP armazena essa string no objeto de exceção no momento em que a exceção é criada, e getMessage() simplesmente a lê de volta.

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

Dois fatos importantes a lembrar:

• Não recebe argumentos e sempre retorna uma string.
• Se nenhuma mensagem foi passada ao construtor, ele retorna uma string vazia (""), e não null.

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

getMessage() é definido na classe base Exception (e em Error), portanto está disponível em todas as exceções nativas e personalizadas — RuntimeException, InvalidArgumentException, TypeError e qualquer classe que as estenda.

Sintaxe

final public Exception::getMessage(): string

O método é final, o que significa que as subclasses não podem substituí-lo — a mensagem que você passa para new Exception("...") é exatamente o que você recebe de volta.

Uso básico

Para ler uma mensagem, capture a exceção em um bloco try/catch. O bloco try contém o código que pode falhar; o bloco catch é executado apenas se uma exceção for lançada.

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

Saída:

Caught: Cannot divide by zero.

InvalidArgumentException estende Exception, portanto o bloco catch (Exception $e) ainda a captura, e getMessage() retorna a string personalizada que passamos ao lançar.

Casos de uso práticos

Registro de erros

Um padrão comum é escrever a mensagem em um log para que você possa investigar falhas posteriormente. Combine getMessage() com getCode(), getFile() e getLine() para entradas de log mais completas.

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

Saída (a data varia):

[2026-06-21] Database connection failed

Exibindo uma mensagem segura ao usuário

As mensagens de exceção frequentemente contêm detalhes técnicos. Use getMessage() para seus logs, mas exiba aos usuários uma mensagem genérica em produção para não vazar informações internas como caminhos de arquivos ou 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. os outros getters de exceção

getMessage() é um dos vários métodos somente leitura em um objeto de exceção. Saber o que cada um retorna ajuda a escolher o correto:

Se você quiser tudo de uma vez para depuração, converter a exceção para string (via __toString()) fornece um dump formatado que já inclui a mensagem, o arquivo, a linha e o rastreamento.

Armadilhas

• Mensagem vazia, não null. Como mostrado acima, uma exceção sem mensagem retorna "". Código como if ($e->getMessage()) tratará isso como falso — proteja-se disso se uma mensagem vazia tiver significado em seu domínio.
• getMessage() é final. Você não pode substituí-lo para transformar o texto. Para personalizar o que os chamadores veem, passe a string desejada ao construtor (geralmente via parent::__construct($message) em uma classe de exceção personalizada).
• fopen() não lança exceções por padrão. Muitas funções PHP emitem avisos e retornam false em vez de lançar. No exemplo de arquivo abaixo, verificamos o valor de retorno e lançamos manualmente; funções como essas não preencherão getMessage() por conta própria, a menos que você converta o aviso em uma exceção (por exemplo, com set_error_handler()).

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

Saída:

Error message: File not found

Aqui abrimos um arquivo, detectamos a falha verificando o valor de retorno de fopen() e lançamos uma Exception com uma mensagem personalizada. getMessage() então recupera essa string para que possamos exibi-la ou registrá-la. Para uma limpeza garantida independentemente do sucesso ou falha, você adicionaria um bloco finally.

Conclusão

Exception::getMessage() retorna a mensagem de erro armazenada em uma exceção capturada — a string que você passou ao construtor, ou uma string vazia se nenhuma foi fornecida. É o getter de exceção mais simples e mais usado, ideal para registro de logs, depuração e geração de feedback voltado ao usuário. Combine-o com os outros getters como getCode() e getTrace() para relatórios de erro completos, e revise o modelo geral de tratamento de exceções do PHP para usá-lo de forma eficaz.

Prática