Base de conhecimentoCentro de Exames
PT · PTPortuguês (Portugal)
Escolher idioma13

CKTIS / PHP

Exception::getMessage — ler a mensagem de uma exceção

Lê o texto de uma exceção capturada, distingue-o do código e do rasto da pilha e decide o que registar e o que apresentar ao utilizador.

Versão: PHP 8.3; extension availability may vary

Sintaxe

final public function getMessage(): string

$e->getMessage()

Exception::getMessage devolve a mensagem de um objeto de exceção como string. É um método de instância público, sem argumentos; final significa que as subclasses não o podem redefinir. :: identifica a classe no nome do método; para o invocar no objeto, usa ->: $e->getMessage(). Em PHP 8.3, invocá-lo em new \Exception() sem mensagem devolve a cadeia de caracteres vazia ''.

catch (\Exception $e) captura objetos \Exception e das suas subclasses, mas não objetos \Error. Para tratar ambas as hierarquias, usa catch (\Throwable $e): a interface comum também disponibiliza getMessage(). Isto não captura avisos comuns que não sejam lançados como objetos. O \ inicial indica o nome global, mesmo dentro de um espaço de nomes.

getMessage() não devolve o código nem o rasto da pilha; para isso, usa getCode() e getTrace(), respetivamente. Também não inclui a mensagem da exceção anterior. Obtém o objeto anterior com getPrevious() e verifica se o resultado não é null antes de invocares getMessage() nesse objeto.

Não baseies as decisões do programa no texto da mensagem. Usa um tipo de exceção ou um código com significado documentado. Em produção, não mostres mensagens de exceção sem as filtrar: podem conter caminhos ou dados sensíveis. Apresenta uma mensagem segura e regista apenas detalhes de diagnóstico devidamente filtrados.

Exemplos

<?php

try {
    $cause = new \Exception('Invalid row format');
    throw new \Exception('Import failed', previous: $cause);
} catch (\Exception $e) {
    echo $e->getMessage(), "\n";

    $previous = $e->getPrevious();
    if ($previous !== null) {
        echo $previous->getMessage(), "\n";
    }
}

Resultado

Import failed
Invalid row format

A primeira linha mostra a mensagem da exceção capturada. A segunda só aparece porque o código obtém o objeto anterior e invoca `getMessage()` nesse objeto em separado.

Lições relacionadas

  • PHP · Lição 41 · Avançado · Versão: 2
  • PHP · Lição 67 · Avançado · Versão: 2
  • PHP · Lição 68 · Avançado · Versão: 2
  • PHP · Lição 69 · Avançado · Versão: 2
  • PHP · Lição 70 · Avançado · Versão: 2
  • PHP · Lição 75 · Avançado · Versão: 2
  • PHP · Lição 82 · Avançado · Versão: 2
  • PHP · Lição 20 · Intermédio · Versão: 3

Fontes