PHP try catch : gérer les exceptions, finally et Throwable

En PHP, vous placez le code qui peut échouer dans try { ... } et traitez l'échec dans catch (Exception $e) { ... }. Si quoi que ce soit dans le bloc try lève une exception, PHP saute directement au catch correspondant, et $e->getMessage() vous dit ce qui n'a pas marché. Si rien n'est levé, le bloc catch est sauté.

<?php
function divide(int $a, int $b): float
{
    if ($b === 0) {
        throw new InvalidArgumentException('Cannot divide by zero');
    }
    return $a / $b;
}

try {
    echo divide(10, 4), "\n";
    echo divide(10, 0), "\n";      // exception: the next line never runs
    echo "not printed\n";
} catch (InvalidArgumentException $e) {
    echo 'Error: ', $e->getMessage(), "\n";
}

echo "The script keeps going\n";

Remplacez divide(10, 0) par divide(10, 5) et relancez : pas d'exception, donc not printed s'affiche et le bloc catch est sauté. Sans try, l'exception terminerait le script avec une erreur fatale « Uncaught ». Comment lever vos propres exceptions et écrire des classes d'exception est expliqué sur la page des exceptions.

La syntaxe de try catch

La forme complète a trois parties. Seul try est obligatoire, plus au moins un catch ou un finally :

try {
    // code that may throw
} catch (SomeException $e) {
    // runs if SomeException (or a subclass) was thrown
} catch (OtherException | ThirdException $e) {
    // runs for either of these types
} finally {
    // always runs, thrown or not
}

Le type dans catch décide de ce qu'il intercepte : la classe elle-même et toutes les classes qui l'étendent. Depuis PHP 8.0, la variable est facultative quand vous n'en avez pas besoin : catch (JsonException) { ... }.

Intercepter Exception, Error ou Throwable

Depuis PHP 7, les échecs que PHP détecte lui-même (appel d'une méthode inexistante, mauvais type d'argument, division par zéro) lèvent une Error, pas une Exception, et PHP 8 a transformé beaucoup d'anciens warnings en TypeError et ValueError. Les deux implémentent l'interface Throwable, mais aucune n'étend l'autre, donc catch (Exception $e) n'intercepte pas une Error :

Throwable
├── Exception                 (problems a program expects and handles)
│   ├── InvalidArgumentException, RuntimeException, JsonException, ...
└── Error                     (engine errors, usually a bug in the code)
    ├── TypeError
    ├── ValueError
    ├── ArithmeticError
    │   └── DivisionByZeroError
    └── UnhandledMatchError, ...

Exécutez ceci pour voir quel catch traite chaque problème :

<?php
$problems = [
    'divide by zero' => fn () => 10 % 0,
    'wrong type'     => fn () => strlen([]),
    'bad value'      => fn () => str_repeat('x', -1),
    'missing method' => fn () => (new stdClass())->save(),
    'own exception'  => fn () => throw new RuntimeException('disk full'),
];

foreach ($problems as $label => $run) {
    try {
        $run();
    } catch (Exception $e) {
        echo "$label: caught as Exception (", get_class($e), ")\n";
    } catch (Error $e) {
        echo "$label: caught as Error (", get_class($e), ")\n";
    }
}

Alors, laquelle intercepter ?

• catch (SomeSpecificException $e) quand vous savez ce qui peut mal tourner et quoi faire. C'est le cas de la plupart du code.
• catch (Exception $e) pour « tout ce qu'une bibliothèque ou mon code a levé volontairement ».
• catch (Throwable $e) au niveau le plus extérieur (un gestionnaire de requêtes, un exécuteur de tâches) pour journaliser chaque échec, erreurs de PHP comprises, et afficher un message correct.

Intercepter plusieurs types d'exceptions

Écrivez plusieurs blocs catch pour traiter différents types de façons différentes. PHP les essaie de haut en bas et utilise la première correspondance, donc un type précis doit venir avant son parent, sinon le parent interceptera tout en premier. Quand plusieurs types reçoivent le même traitement, combinez-les dans un seul catch avec | :

<?php
function loadUser(mixed $id): array
{
    if (!is_int($id)) {
        throw new InvalidArgumentException("ID must be an integer, got " . get_debug_type($id));
    }
    if ($id < 1) {
        throw new DomainException("ID must be positive, got $id");
    }
    if ($id > 100) {
        throw new OutOfBoundsException("No user with ID $id");
    }
    return ['id' => $id, 'name' => 'User ' . $id];
}

foreach ([7, 'abc', -5, 500] as $id) {
    try {
        $user = loadUser($id);
        echo "Found {$user['name']}\n";
    } catch (OutOfBoundsException $e) {
        echo "404: {$e->getMessage()}\n";
    } catch (InvalidArgumentException | DomainException $e) {
        echo '400: ', $e->getMessage(), ' (', get_class($e), ")\n";
    }
}

Les trois classes étendent Exception, donc un seul catch (Exception $e) les intercepterait aussi, mais le code ne pourrait plus répondre 404 pour l'une et 400 pour les autres.

finally : du code qui s'exécute toujours

Un bloc finally s'exécute après try et catch quelle que soit leur façon de se terminer : normalement, avec une exception interceptée, avec une exception que personne n'a interceptée, ou avec un return. C'est l'endroit pour libérer ce que le bloc try a acquis : fermer un fichier, libérer un verrou, arrêter un chronomètre.

<?php
function process(string $file): string
{
    $handle = fopen($file, 'w');
    echo "opened $file\n";
    try {
        fwrite($handle, "data\n");
        if ($file === 'bad.txt') {
            throw new RuntimeException('write check failed');
        }
        return 'saved';           // finally still runs before returning
    } finally {
        fclose($handle);
        echo "closed $file\n";
    }
}

echo process('good.txt'), "\n\n";

try {
    echo process('bad.txt'), "\n";
} catch (RuntimeException $e) {
    echo 'Failed: ', $e->getMessage(), "\n";
}

Pour good.txt, le fichier est fermé avant l'affichage de saved, car finally s'exécute avant que la fonction ne renvoie réellement sa valeur. Pour bad.txt, il n'y a pas de catch dans process() : finally ferme le fichier, puis l'exception remonte jusqu'au catch de l'appelant.

Évitez return dans finally : il remplace la valeur renvoyée par le bloc try et jette en silence une exception qui était en train de remonter :

function f(): string
{
    try {
        return 'from try';
    } finally {
        return 'from finally';
    }
}

function g(): string
{
    try {
        throw new RuntimeException('lost');
    } finally {
        return 'no exception reaches the caller';
    }
}

echo f(); // from finally
echo g(); // no exception reaches the caller

Relancer ou envelopper une exception

Parfois, un bloc catch ne peut traiter qu'une partie d'un problème : le journaliser, nettoyer, puis le laisser continuer. throw $e; relance la même exception. Plus souvent, vous voulez ajouter du contexte tout en gardant la cause d'origine, et c'est à cela que sert le troisième argument du constructeur, $previous :

<?php
class ConfigException extends RuntimeException {}

function readConfig(string $json): array
{
    try {
        return json_decode($json, true, flags: JSON_THROW_ON_ERROR);
    } catch (JsonException $e) {
        // Wrap: a clearer message, the original kept as "previous"
        throw new ConfigException('config.json is not valid JSON', 0, $e);
    }
}

try {
    print_r(readConfig('{"debug": true}'));
    readConfig('{"debug": true,}');
} catch (ConfigException $e) {
    echo $e->getMessage(), "\n";
    echo 'Caused by: ', get_class($e->getPrevious()), ': ', $e->getPrevious()->getMessage(), "\n";
}

L'appelant traite une seule ConfigException et n'a pas besoin de savoir que la configuration est en JSON, alors que getPrevious() garde le détail de bas niveau pour le journal.

Exceptions non interceptées et gestionnaire global

Une exception qu'aucun catch ne traite termine le script avec une erreur fatale qui indique la classe, le message, le fichier et la ligne, ainsi qu'une trace de la pile d'appels :

<?php
// No try/catch anywhere in this file
function charge(int $cents): void
{
    if ($cents <= 0) {
        throw new DomainException("Amount must be positive, got $cents");
    }
}

charge(500);
echo "first charge ok\n";
charge(-1);
echo "never printed\n";

PHP affiche first charge ok puis :

PHP Fatal error:  Uncaught DomainException: Amount must be positive, got -1 in /home/index.php:6
Stack trace:
#0 /home/index.php(12): charge()
#1 {main}
  thrown in /home/index.php on line 6

Sur un site en ligne, ce message ne doit jamais atteindre les visiteurs. set_exception_handler() enregistre une fonction qui reçoit toute exception que personne n'a interceptée, un seul endroit pour la journaliser et afficher une page polie :

<?php
set_exception_handler(function (Throwable $e) {
    // In production: write $e to a log file here
    echo "<h1>Something went wrong</h1>\n";
    echo "<p>We have been notified. Please try again later.</p>\n";
    echo '<!-- ', get_class($e), ': ', htmlspecialchars($e->getMessage()), " -->\n";
});

echo "<p>Loading your dashboard...</p>\n";
throw new RuntimeException('Database timeout');

Le gestionnaire s'exécute, puis le script s'arrête ; il n'y a aucun moyen de reprendre après le throw. L'affichage même du texte d'erreur de PHP sur la page est contrôlé par display_errors, présenté dans l'affichage des erreurs.

Les warnings ne sont pas des exceptions

try/catch ne voit que ce qui est levé. Beaucoup d'anciennes fonctions PHP ne lèvent rien : elles renvoient false ou null et, au plus, affichent un warning. json_decode() est un cas typique, et l'entourer de try ne change rien tant que vous ne lui demandez pas de lever une exception :

<?php
$broken = '{"name": "Ada",}';

try {
    $data = json_decode($broken, true);
    var_dump($data);                    // NULL, and no exception
    echo 'Error: ', json_last_error_msg(), "\n";
} catch (JsonException $e) {
    echo "never reached\n";
}

try {
    $data = json_decode($broken, true, flags: JSON_THROW_ON_ERROR);
} catch (JsonException $e) {
    echo 'Caught: ', $e->getMessage(), "\n";
}

Pour les fonctions sans option de ce genre, vérifiez la valeur de retour (if ($handle === false)), ou vérifiez d'abord la condition préalable (file_exists(), isset()). Un set_error_handler() qui lève une ErrorException transforme chaque warning en vraie exception si vous voulez une seule règle pour tout.

Recette : valider une saisie de formulaire avec des exceptions

Un modèle pratique : les fonctions de validation lèvent des exceptions, la page les intercepte et affiche le message à côté du formulaire. Exécutez-le, puis tapez un âge dans le formulaire et cliquez sur Send : le même script s'exécute à nouveau avec $_POST rempli.

<?php
function validAge(string $raw): int
{
    if (trim($raw) === '') {
        throw new InvalidArgumentException('Please enter your age.');
    }
    $age = filter_var($raw, FILTER_VALIDATE_INT);
    if ($age === false) {
        throw new InvalidArgumentException('Age must be a whole number.');
    }
    if ($age < 13) {
        throw new RangeException('You must be at least 13 to sign up.');
    }
    return $age;
}

$raw = $_POST['age'] ?? '';
$message = '';

if (($_SERVER['REQUEST_METHOD'] ?? 'GET') === 'POST') {
    try {
        $age = validAge($raw);
        $message = "<p style=\"color:green\">Welcome, age $age accepted.</p>";
    } catch (InvalidArgumentException | RangeException $e) {
        $message = '<p style="color:red">' . htmlspecialchars($e->getMessage()) . '</p>';
    }
}
?>
<form method="post">
    <label>Age <input name="age" value="<?= htmlspecialchars($raw) ?>"></label>
    <button>Send</button>
</form>
<?= $message ?>

Essayez un champ vide, twelve, 9 et 30. Chaque règle qui échoue lève une exception avec son propre message, et un seul catch les transforme toutes en la même ligne rouge. La page sur les formulaires va plus loin avec plusieurs champs et des erreurs à côté de chacun.