getMessage()

Introduzione

La gestione delle eccezioni in PHP consente di separare il codice che rileva un problema dal codice che vi risponde. Quando qualcosa va storto, si lancia (throw) un oggetto eccezione che risale lo stack delle chiamate fino a quando un blocco catch corrispondente lo gestisce. Quell'oggetto contiene i dettagli di ciò che è accaduto — e il più comunemente utilizzato di questi dettagli è il messaggio di errore leggibile dall'utente.

Questo capitolo tratta Exception::getMessage(), il metodo che restituisce quella stringa del messaggio. Imparerai cosa restituisce, come differisce dagli altri metodi "getter" sull'oggetto eccezione, le insidie comuni e come usarlo per errori visibili all'utente, logging e debugging.

Cosa restituisce getMessage()

getMessage() restituisce la stringa del messaggio che è stata passata come primo argomento al costruttore dell'eccezione. PHP memorizza quella stringa sull'oggetto eccezione nel momento in cui l'eccezione viene creata, e getMessage() semplicemente la rilegge.

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

Due fatti da ricordare:

• Non accetta argomenti e restituisce sempre una string.
• Se nessun messaggio è stato passato al costruttore, restituisce una stringa vuota (""), non null.

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

getMessage() è definito sulla classe base Exception (e su Error), quindi è disponibile su ogni eccezione built-in e personalizzata — RuntimeException, InvalidArgumentException, TypeError e qualsiasi classe che le estenda.

Sintassi

final public Exception::getMessage(): string

Il metodo è final, il che significa che le sottoclassi non possono sovrascriverlo — il messaggio che passi a new Exception("...") è esattamente quello che ottieni indietro.

Utilizzo di base

Per leggere un messaggio, cattura l'eccezione in un blocco try/catch. Il blocco try contiene il codice che potrebbe fallire; il blocco catch viene eseguito solo se viene lanciata un'eccezione.

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

Output:

Caught: Cannot divide by zero.

InvalidArgumentException estende Exception, quindi il blocco catch (Exception $e) la cattura comunque, e getMessage() restituisce la stringa personalizzata che abbiamo passato al momento del lancio.

Casi d'uso pratici

Logging degli errori

Un pattern comune è quello di scrivere il messaggio in un log in modo da poter investigare i fallimenti in seguito. Abbina getMessage() a getCode(), getFile() e getLine() per voci di log più ricche.

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

Output (la data varierà):

[2026-06-21] Database connection failed

Mostrare un messaggio sicuro all'utente

I messaggi delle eccezioni spesso contengono dettagli tecnici. Usa getMessage() per i tuoi log, ma mostra agli utenti un messaggio generico in produzione per non esporre dettagli interni come percorsi di file 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. gli altri getter delle eccezioni

getMessage() è uno dei vari metodi di sola lettura su un oggetto eccezione. Sapere cosa restituisce ciascuno aiuta a scegliere quello giusto:

Se vuoi tutto in una volta per il debugging, il cast dell'eccezione in una stringa (tramite __toString()) restituisce un dump formattato che include già il messaggio, il file, la riga e il trace.

Insidie

• Messaggio vuoto, non null. Come mostrato sopra, un'eccezione senza messaggio restituisce "". Codice come if ($e->getMessage()) lo tratterà come falsy — gestisci questo caso se un messaggio vuoto è significativo nel tuo dominio.
• getMessage() è final. Non puoi sovrascriverlo per trasformare il testo. Per personalizzare ciò che i chiamanti vedono, passa la stringa desiderata al costruttore (spesso tramite parent::__construct($message) in una classe di eccezione personalizzata).
• fopen() non lancia eccezioni per default. Molte funzioni PHP emettono warning e restituiscono false invece di lanciare. Nell'esempio del file qui sotto controlliamo il valore di ritorno e lanciamo manualmente; funzioni come queste non popolano getMessage() da sole a meno che non si converta il warning in un'eccezione (ad esempio con set_error_handler()).

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

Output:

Error message: File not found

Qui apriamo un file, rileviamo il fallimento controllando il valore restituito da fopen(), e lanciamo un'Exception con un messaggio personalizzato. getMessage() recupera quindi quella stringa in modo da poterla visualizzare o registrare nel log. Per una pulizia garantita indipendentemente dal successo o dal fallimento, si aggiungerebbe un blocco finally.

Conclusione

Exception::getMessage() restituisce il messaggio di errore memorizzato su un'eccezione catturata — la stringa che hai passato al costruttore, oppure una stringa vuota se non ne è stata fornita nessuna. È il getter di eccezione più semplice e più utilizzato, ideale per il logging, il debugging e la produzione di feedback visibile all'utente. Combinalo con gli altri getter come getCode() e getTrace() per report di errori completi, e consulta il modello generale di gestione delle eccezioni di PHP per usarlo efficacemente.

Esercitazione