getMessage()

Introduction

La gestion des exceptions en PHP vous permet de séparer le code qui détecte un problème du code qui y répond. Lorsque quelque chose tourne mal, vous throw un objet exception qui remonte la pile d'appels jusqu'à ce qu'un bloc catch correspondant le traite. Cet objet contient des détails sur ce qui s'est passé — et le détail le plus couramment utilisé est le message d'erreur lisible par un humain.

Ce chapitre couvre Exception::getMessage(), la méthode qui retourne cette chaîne de message. Vous apprendrez ce qu'elle retourne, en quoi elle diffère des autres méthodes « getter » de l'objet exception, les pièges courants, et comment l'utiliser pour les erreurs destinées à l'utilisateur, la journalisation et le débogage.

Ce que retourne getMessage()

getMessage() retourne la chaîne de message qui a été passée comme premier argument au constructeur de l'exception. PHP stocke cette chaîne sur l'objet exception au moment de sa création, et getMessage() se contente de la relire.

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

Deux faits à retenir :

• Elle ne prend aucun argument et retourne toujours une string.
• Si aucun message n'a été passé au constructeur, elle retourne une chaîne vide (""), pas null.

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

getMessage() est définie sur la classe de base Exception (et sur Error), elle est donc disponible sur toutes les exceptions intégrées et personnalisées — RuntimeException, InvalidArgumentException, TypeError, et toute classe qui les étend.

Syntaxe

final public Exception::getMessage(): string

La méthode est final, ce qui signifie que les sous-classes ne peuvent pas la redéfinir — le message que vous passez à new Exception("...") est exactement ce que vous récupérez.

Utilisation de base

Pour lire un message, capturez l'exception dans un bloc try/catch. Le bloc try contient le code susceptible d'échouer ; le bloc catch ne s'exécute que si une exception est levée.

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

Sortie :

Caught: Cannot divide by zero.

InvalidArgumentException étend Exception, donc le bloc catch (Exception $e) la capture quand même, et getMessage() retourne la chaîne personnalisée que nous avons passée lors du lancement.

Cas d'utilisation pratiques

Journalisation des erreurs

Un modèle courant consiste à écrire le message dans un journal afin d'investiguer les échecs ultérieurement. Associez getMessage() à getCode(), getFile(), et getLine() pour des entrées de journal plus riches.

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

Sortie (la date variera) :

[2026-06-21] Database connection failed

Afficher un message sécurisé à l'utilisateur

Les messages d'exception contiennent souvent des détails techniques. Utilisez getMessage() pour vos journaux, mais affichez un message générique aux utilisateurs en production afin de ne pas exposer des informations internes telles que des chemins de fichiers ou du 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. les autres getters d'exception

getMessage() est l'une des plusieurs méthodes en lecture seule d'un objet exception. Savoir ce que chacune retourne vous aide à choisir la bonne :

Si vous voulez tout voir d'un coup pour le débogage, convertir l'exception en chaîne (via __toString()) donne un dump formaté qui inclut déjà le message, le fichier, la ligne et la trace.

Pièges à éviter

• Message vide, pas null. Comme indiqué ci-dessus, une exception sans message retourne "". Du code comme if ($e->getMessage()) considérera cela comme faux — prenez-en garde si un message vide a une signification dans votre domaine.
• getMessage() est final. Vous ne pouvez pas la redéfinir pour transformer le texte. Pour personnaliser ce que les appelants voient, passez la chaîne souhaitée au constructeur (souvent via parent::__construct($message) dans une classe d'exception personnalisée).
• fopen() ne lève pas d'exception par défaut. De nombreuses fonctions PHP émettent des avertissements et retournent false au lieu de lever une exception. Dans l'exemple de fichier ci-dessous, nous vérifions la valeur de retour et lançons manuellement ; de telles fonctions ne rempliront pas getMessage() d'elles-mêmes, sauf si vous convertissez l'avertissement en exception (par exemple avec set_error_handler()).

Exemple complet

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

Sortie :

Error message: File not found

Ici, nous ouvrons un fichier, détectons l'échec en vérifiant la valeur de retour de fopen(), et lançons une Exception avec un message personnalisé. getMessage() récupère ensuite cette chaîne afin que nous puissions l'afficher ou la journaliser. Pour un nettoyage garanti indépendamment du succès ou de l'échec, vous ajouteriez un bloc finally.

Conclusion

Exception::getMessage() retourne le message d'erreur stocké sur une exception capturée — la chaîne que vous avez passée au constructeur, ou une chaîne vide si aucune n'a été fournie. C'est le getter d'exception le plus simple et le plus utilisé, idéal pour la journalisation, le débogage et la production de retours destinés à l'utilisateur. Combinez-le avec les autres getters comme getCode() et getTrace() pour des rapports d'erreurs complets, et consultez le modèle global de gestion des exceptions en PHP pour l'utiliser efficacement.

Pratique