getPrevious()

Introduction

Exception::getPrevious() retourne l'exception passée en tant que troisième argument au constructeur d'une exception PHP — l'exception à l'origine de l'exception actuelle. Elle est définie sur la classe de base Exception (et Error), donc tous les types d'exceptions PHP en héritent.

Cette page explique ce que retourne getPrevious(), comment construire une chaîne d'exceptions « enveloppées », comment parcourir cette chaîne et les erreurs courantes à éviter.

Syntaxe et valeur de retour

final public Throwable::getPrevious(): ?Throwable

• Paramètres : aucun.
• Retourne : le Throwable précédent (une Exception ou une Error) si l'un a été défini, sinon null.
• La méthode est final, vous ne pouvez donc pas la redéfinir dans vos propres sous-classes d'exceptions.

L'exception « précédente » est définie lorsque vous construisez une exception avec un troisième argument :

throw new RuntimeException("High-level failure", 0, $originalException);
//                          message            ^code  ^previous

Exemple de base

Lorsque vous relancez une exception, passez l'originale en tant que troisième argument du constructeur afin de ne pas perdre le contexte :

<?php
try {
    try {
        throw new Exception("Inner error");
    } catch (Exception $inner) {
        // Wrap the low-level error in a more meaningful one,
        // keeping the original as "previous".
        throw new Exception("Outer error", 0, $inner);
    }
} catch (Exception $e) {
    echo "Caught: " . $e->getMessage() . "\n";

    $previous = $e->getPrevious();
    if ($previous !== null) {
        echo "Caused by: " . $previous->getMessage() . "\n";
    }
}
?>

Résultat :

Caught: Outer error
Caused by: Inner error

getPrevious() retourne l'objet $inner que vous avez passé, ce qui vous permet de lire son message, son code ou sa trace de pile exactement comme vous le feriez pour n'importe quelle exception.

Pourquoi envelopper les exceptions

Un schéma courant consiste à intercepter une exception technique de bas niveau (une requête de base de données échouée, un fichier introuvable) et à relancer une exception de plus haut niveau, spécifique au domaine — sans perdre la cause d'origine :

<?php
function loadUser(int $id): array
{
    try {
        // Pretend this talks to a database and fails.
        throw new RuntimeException("SQLSTATE[HY000]: connection refused");
    } catch (RuntimeException $dbError) {
        // Callers care about "could not load user", not SQL internals,
        // but we keep the SQL error available via getPrevious().
        throw new RuntimeException("Unable to load user #$id", 0, $dbError);
    }
}

try {
    loadUser(42);
} catch (RuntimeException $e) {
    echo $e->getMessage() . "\n";
    echo "Root cause: " . $e->getPrevious()->getMessage() . "\n";
}
?>

Résultat :

Unable to load user #42
Root cause: SQLSTATE[HY000]: connection refused

Cela permet de garder des messages d'erreur de haut niveau clairs tout en conservant les détails techniques pour la journalisation et le débogage.

Parcourir toute la chaîne d'exceptions

Une exception précédente peut elle-même avoir une exception précédente. Pour inspecter toute la chaîne, itérez tant que getPrevious() retourne une valeur non-null :

<?php
$a = new Exception("Level 1: low-level cause");
$b = new Exception("Level 2: mid-level wrapper", 0, $a);
$c = new Exception("Level 3: top-level error", 0, $b);

$current = $c;
while ($current !== null) {
    echo $current->getMessage() . "\n";
    $current = $current->getPrevious();
}
?>

Résultat :

Level 3: top-level error
Level 2: mid-level wrapper
Level 1: low-level cause

Pièges courants

• L'absence d'exception précédente retourne null. Si vous créez une exception sans troisième argument, getPrevious() retourne null. Vérifiez toujours avec !== null (ou une boucle) avant d'appeler des méthodes sur le résultat.
• Le troisième argument du constructeur est l'exception précédente, pas le code. La signature est new Exception($message, $code, $previous). Une erreur fréquente consiste à passer l'exception précédente dans le deuxième emplacement, où PHP attend un code entier.
• Elle est en lecture seule. Il n'existe pas de setPrevious(). La chaîne est fixée à la construction, vous devez donc passer la cause lors de la création de l'exception enveloppante.
• var_dump($e) affiche déjà la chaîne. Lorsque vous convertissez une exception non interceptée en string (ou que vous laissez PHP l'afficher), la trace de l'exception précédente est incluse automatiquement — getPrevious() est utile lorsque vous devez l'inspecter dans le code.

Méthodes associées

getPrevious() fait partie de plusieurs méthodes d'inspection exposées par toute exception PHP :

• getMessage() — le message d'erreur lisible par l'humain.
• getCode() — le code d'erreur numérique.
• getTrace() — la trace de pile sous forme d'array.
• getTraceAsString() — la trace de pile sous forme de string.

Pour une vue d'ensemble de try/catch et des classes d'exceptions personnalisées, consultez PHP Exceptions.

Résumé

getPrevious() récupère l'exception à l'origine de l'exception actuelle, permettant le chaînage d'exceptions : interceptez une erreur de bas niveau, lancez une exception significative de haut niveau, et conservez néanmoins la cause d'origine pour le débogage. Elle retourne null quand aucune exception précédente n'a été définie, pensez donc à le vérifier — ou à boucler dessus — avant d'utiliser le résultat.

Pratique