Exceptions PHP : throw et classes d'exception personnalisées

En PHP, on lève une exception avec throw new Exception('message');. L'exécution s'arrête à cette ligne et saute au bloc catch le plus proche qui accepte le type de l'exception, où $e->getMessage() renvoie le message. Utilisez une classe précise, comme InvalidArgumentException, pour que les appelants puissent distinguer les problèmes.

<?php
function setQuantity(int $qty): string
{
    if ($qty < 1) {
        throw new InvalidArgumentException("Quantity must be at least 1, got $qty");
    }
    return "Quantity set to $qty";
}

try {
    echo setQuantity(3), "\n";
    echo setQuantity(0), "\n";
} catch (InvalidArgumentException $e) {
    echo 'Rejected: ', $e->getMessage(), "\n";
}

Une exception est un objet. throw la fait remonter la pile d'appels jusqu'au premier appelant qui a un catch correspondant, et c'est cet appelant qui décide quoi faire ; la fonction qui a trouvé le problème n'a pas à le savoir. Le fonctionnement de l'interception, de finally et de l'interception de plusieurs types est expliqué sur la page try catch.

Ce que contient un objet exception

Chaque exception porte un message, un code entier, le fichier et la ligne où elle a été créée, et une trace de la pile d'appels. Le constructeur prend ($message, $code, $previous), tous facultatifs :

<?php
function findOrder(int $id): array
{
    throw new RuntimeException("Order $id not found", 404);
}

try {
    findOrder(77);
} catch (RuntimeException $e) {
    echo 'Class:   ', get_class($e), "\n";
    echo 'Message: ', $e->getMessage(), "\n";
    echo 'Code:    ', $e->getCode(), "\n";
    echo 'File:    ', basename($e->getFile()), "\n";
    echo 'Line:    ', $e->getLine(), "\n";
    echo "Trace:\n", $e->getTraceAsString(), "\n";
}

getLine() est la ligne du throw new, pas celle du catch. La trace liste les appels qui y ont mené (#0 /home/index.php(8): findOrder()), et c'est en général la première chose à lire quand une erreur apparaît dans un journal. Convertir l'exception en chaîne (echo $e; ou (string) $e) affiche tout cela au format standard de PHP.

Les classes d'exception natives

PHP fournit une famille de classes d'exception dans sa Standard PHP Library (SPL). Lever celle qui nomme le problème rend votre code plus lisible et permet aux appelants d'intercepter de façon ciblée. Toutes celles-ci étendent Exception :

InvalidArgumentException, DomainException, LengthException et OutOfRangeException étendent LogicException ; OutOfBoundsException, RangeException et UnexpectedValueException étendent RuntimeException. Vous pouvez vérifier vous-même les parents de n'importe quelle classe :

<?php
foreach ([InvalidArgumentException::class, RangeException::class, JsonException::class, TypeError::class] as $class) {
    echo $class, ' -> ', implode(' -> ', class_parents($class)), "\n";
}

$e = new OutOfRangeException('Index 9 is out of range');
var_dump($e instanceof LogicException, $e instanceof RuntimeException, $e instanceof Throwable);

TypeError a Error pour parent, pas Exception : elle appartient à la seconde famille, ci-dessous.

Les erreurs que PHP lève lui-même

Depuis PHP 7, et bien plus encore depuis PHP 8, les fonctions et opérateurs de PHP lèvent des sous-classes d'Error pour des problèmes qui étaient autrefois des warnings. Vous les interceptez de la même façon, mais catch (Exception $e) ne les attrapera pas :

<?php
declare(strict_types=1);

$cases = [
    'intdiv by zero'  => fn () => intdiv(10, 0),
    'modulo by zero'  => fn () => 7 % 0,
    'wrong arg type'  => fn () => str_repeat(5, 2),
    'invalid value'   => fn () => array_fill(0, -1, 'x'),
    'too few args'    => fn () => (fn (int $a, int $b) => $a + $b)(1),
    'no match arm'    => fn () => match (99) { 1 => 'one', 2 => 'two' },
    'undefined func'  => fn () => undefined_function(),
];

foreach ($cases as $label => $run) {
    try {
        $run();
    } catch (Error $e) {
        printf("%-16s %-22s %s\n", $label, get_class($e), $e->getMessage());
    }
}

DivisionByZeroError, TypeError, ValueError, ArgumentCountError, UnhandledMatchError et Error simple étendent toutes Error. Chacune signale plus souvent un bug dans le code appelant que des données invalides, c'est pourquoi elles vivent hors de l'arbre Exception. C'est declare(strict_types=1) qui fait de str_repeat(5, 2) une TypeError ; sans lui, PHP convertirait 5 en "5".

Écrire une classe d'exception personnalisée

Une sous-classe d'une ligne suffit souvent : le nom de la classe porte le sens, et les appelants peuvent intercepter exactement ce type. Quand celui qui intercepte a besoin de données (quelle commande, quel montant), ajoutez des propriétés et transmettez le message avec parent::__construct() :

<?php
class PaymentException extends RuntimeException {}

class InsufficientFundsException extends PaymentException
{
    public function __construct(
        public readonly int $balanceCents,
        public readonly int $neededCents,
    ) {
        parent::__construct(sprintf(
            'Insufficient funds: balance %.2f, needed %.2f',
            $balanceCents / 100,
            $neededCents / 100,
        ), 402);
    }

    public function shortfall(): int
    {
        return $this->neededCents - $this->balanceCents;
    }
}

function pay(int $balance, int $amount): string
{
    if ($amount > $balance) {
        throw new InsufficientFundsException($balance, $amount);
    }
    return 'paid';
}

try {
    echo pay(5000, 1200), "\n";
    echo pay(5000, 8000), "\n";
} catch (InsufficientFundsException $e) {
    echo $e->getMessage(), "\n";
    echo 'Top up at least ', $e->shortfall() / 100, " EUR (code {$e->getCode()})\n";
} catch (PaymentException $e) {
    echo 'Payment failed: ', $e->getMessage(), "\n";
}

Choisissez le parent avec soin : étendre RuntimeException (plutôt qu'Exception simple) signifie que le code qui intercepte RuntimeException traite aussi la vôtre. Une petite hiérarchie, une exception de base par bibliothèque ou par module avec des sous-classes précises en dessous, permet aux appelants de choisir entre « tout intercepter des paiements » et « intercepter seulement ce cas ».

Chaîner les exceptions avec previous

Quand vous interceptez une exception de bas niveau et en levez une de plus haut niveau, passez l'originale en troisième argument. Rien n'est perdu : getPrevious() remonte jusqu'à la cause première.

<?php
class ImportException extends RuntimeException {}

function parseRow(string $line, int $n): array
{
    $cols = str_getcsv($line);
    if (count($cols) !== 3) {
        throw new UnexpectedValueException("row $n has " . count($cols) . ' columns, expected 3');
    }
    return $cols;
}

function import(array $lines): int
{
    foreach ($lines as $i => $line) {
        try {
            parseRow($line, $i + 1);
        } catch (UnexpectedValueException $e) {
            throw new ImportException('customers.csv could not be imported', 0, $e);
        }
    }
    return count($lines);
}

try {
    import(['Ada,ada@example.com,UK', 'Linus,linus@example.com']);
} catch (ImportException $e) {
    $level = 0;
    for ($x = $e; $x !== null; $x = $x->getPrevious()) {
        echo str_repeat('  ', $level++), get_class($x), ': ', $x->getMessage(), "\n";
    }
}

L'utilisateur voit « customers.csv could not be imported » ; le journal, en parcourant la chaîne, reçoit aussi « row 2 has 2 columns ». Si une exception chaînée n'est jamais interceptée, l'erreur fatale de PHP affiche toute la chaîne : la cause d'origine d'abord, puis chaque enveloppe sous une ligne Next.

throw comme expression

Depuis PHP 8.0, throw est une expression, il peut donc se placer partout où une valeur est attendue : après ??, dans un ternaire, dans une fonction fléchée. « Obtenir ceci ou échouer » tient alors en une ligne :

<?php
$config = ['host' => 'localhost', 'port' => '5432'];

function setting(array $config, string $key): string
{
    return $config[$key] ?? throw new OutOfBoundsException("Missing setting '$key'");
}

echo setting($config, 'host'), "\n";

$port = (int) $config['port'] ?: throw new DomainException('Port must not be 0');
echo $port, "\n";

$positive = fn (int $n) => $n > 0 ? $n : throw new DomainException("$n is not positive");
echo $positive(8), "\n";

try {
    echo setting($config, 'password'), "\n";
} catch (OutOfBoundsException $e) {
    echo $e->getMessage(), "\n";
}

Quand ne pas lever d'exception

Les exceptions sont pour les situations que la fonction courante ne peut pas traiter et que le déroulement normal ne prévoit pas. Une recherche qui ne trouve rien, un champ facultatif vide ou un utilisateur non connecté sont des résultats ordinaires : renvoyez null, false ou un tableau vide et laissez l'appelant vérifier, et gardez les exceptions pour les cas où continuer serait une erreur.

<?php
$users = ['ada' => 'Ada Lovelace', 'linus' => 'Linus Torvalds'];

// Ordinary outcome: "not found" is a normal answer, so return null
function findUser(array $users, string $handle): ?string
{
    return $users[$handle] ?? null;
}

// Broken input: an empty handle is a bug in the caller, so throw
function requireHandle(string $handle): string
{
    if ($handle === '') {
        throw new InvalidArgumentException('Handle must not be empty');
    }
    return strtolower($handle);
}

foreach (['ADA', 'grace', ''] as $input) {
    try {
        $name = findUser($users, requireHandle($input));
        echo $input, ': ', $name ?? 'no such user', "\n";
    } catch (InvalidArgumentException $e) {
        echo 'Bug: ', $e->getMessage(), "\n";
    }
}

Deux autres habitudes gardent le code des exceptions lisible : n'interceptez jamais une exception juste pour l'ignorer (un catch (Exception $e) {} vide cache le prochain vrai bug), et levez des classes précises plutôt qu'un simple Exception, pour qu'un appelant ne soit jamais obligé de tout intercepter pour traiter un seul cas.