Hiérarchie d'exceptions personnalisées

Fait partie de la section Programmation Orientée Objet du Journey PHP de Coddy — leçon 67 sur 91.

Alors que les classes d'exception intégrées de PHP couvrent les scénarios courants, les applications réelles ont souvent besoin de types d'erreurs plus spécifiques. Créer une hiérarchie d'exceptions personnalisée vous permet de définir des exceptions qui correspondent à votre domaine et de les intercepter à différents niveaux de spécificité.

Pour créer une exception personnalisée, étendez simplement la classe Exception ou l'une de ses sous-classes :

<?php
class PaymentException extends Exception {}

class InsufficientFundsException extends PaymentException {
    public function __construct(
        private float $required,
        private float $available
    ) {
        parent::__construct("Need $required but only $available available");
    }
    
    public function getShortfall(): float {
        return $this->required - $this->available;
    }
}

Remarquez comment InsufficientFundsException étend PaymentException, et non Exception directement. Cela crée une hiérarchie où vous pouvez intercepter toutes les exceptions liées au paiement avec un seul bloc catch, ou gérer les exceptions spécifiques individuellement.

Les exceptions personnalisées peuvent inclure des propriétés et des méthodes supplémentaires pertinentes pour l'erreur. Ici, getShortfall() fournit des informations utiles qu'une exception générique ne pourrait pas offrir :

<?php
class Wallet {
    public function __construct(private float $balance) {}
    
    public function pay(float $amount): void {
        if ($amount > $this->balance) {
            throw new InsufficientFundsException($amount, $this->balance);
        }
        $this->balance -= $amount;
    }
}

Une hiérarchie d'exceptions bien conçue rend votre code plus facile à maintenir. Lors de l'interception d'exceptions, vous pouvez être aussi large ou spécifique que nécessaire, et les objets d'exception eux-mêmes transportent un contexte significatif sur ce qui s'est mal passé.

Défi

Facile

Construisons un système de traitement des commandes avec une hiérarchie d'exceptions personnalisées qui gère différents types d'échecs de commande. Vous allez créer des exceptions qui transportent un contexte significatif sur ce qui s'est mal passé, rendant la gestion des erreurs plus précise et informative.

Vous organiserez votre code sur quatre fichiers :

OrderException.php — Créez une classe de base OrderException qui étend Exception. Elle sert de parent pour toutes les exceptions liées aux commandes, vous permettant de capturer n'importe quel problème de commande avec un seul bloc catch si nécessaire.
OutOfStockException.php — Créez une classe OutOfStockException qui étend OrderException. Cette exception doit accepter un nom de produit et la quantité demandée dans son constructeur. Utilisez la promotion de constructeur pour ces propriétés privées. Appelez le constructeur parent avec un message au format "[productName] is out of stock (requested: [quantity])". Ajoutez une méthode getProductName(): string qui retourne le nom du produit.
InvalidQuantityException.php — Créez une classe InvalidQuantityException qui étend OrderException. Cette exception doit accepter une valeur de quantité dans son constructeur en utilisant la promotion de constructeur comme propriété privée. Appelez le constructeur parent avec le message "Invalid quantity: [quantity]". Ajoutez une méthode getQuantity(): int qui retourne la valeur de la quantité.
main.php — Incluez les trois fichiers d'exception. Vous recevrez deux entrées : un nom de produit et une quantité (sous forme de chaîne de caractères qui doit être convertie en entier).
En fonction de la valeur de la quantité, lancez l'exception appropriée :
- Si la quantité est inférieure à 1, lancez une InvalidQuantityException
- Si la quantité est supérieure à 100, lancez une OutOfStockException (simulant un stock insuffisant)
- Sinon, affichez "Order placed: [quantity]x [productName]"
Capturez les exceptions en utilisant la hiérarchie. Capturez d'abord InvalidQuantityException et affichez "Quantity error: [message] (value: [quantity])" en utilisant le message de l'exception et la méthode getQuantity(). Ensuite, capturez OutOfStockException et affichez "Stock error: [message] (product: [productName])" en utilisant le message de l'exception et la méthode getProductName().

Cette hiérarchie vous permet de gérer des exceptions spécifiques individuellement tout en ayant la possibilité de capturer tous les problèmes liés aux commandes via la classe de base OrderException. Les méthodes personnalisées sur chaque exception fournissent un contexte qu'une exception générique ne pourrait pas offrir.

Aide-mémoire

Créez des exceptions personnalisées en étendant la classe Exception ou ses sous-classes :

<?php
class PaymentException extends Exception {}

class InsufficientFundsException extends PaymentException {
    public function __construct(
        private float $required,
        private float $available
    ) {
        parent::__construct("Need $required but only $available available");
    }
    
    public function getShortfall(): float {
        return $this->required - $this->available;
    }
}

Les exceptions personnalisées peuvent former une hiérarchie en étendant d'autres exceptions personnalisées. Cela permet d'intercepter les exceptions à différents niveaux de spécificité : intercepter toutes les exceptions liées au paiement avec PaymentException, ou gérer individuellement des exceptions spécifiques comme InsufficientFundsException.

Les exceptions personnalisées peuvent inclure des propriétés et des méthodes supplémentaires pour fournir un contexte sur l'erreur :

<?php
class Wallet {
    public function __construct(private float $balance) {}
    
    public function pay(float $amount): void {
        if ($amount > $this->balance) {
            throw new InsufficientFundsException($amount, $this->balance);
        }
        $this->balance -= $amount;
    }
}

Utilisez la promotion de propriété de constructeur pour définir des propriétés directement dans les paramètres du constructeur. Appelez parent::__construct() pour définir le message de l'exception.

Essayez vous-même

<?php
// Inclure tous les fichiers d'exception
require_once 'OrderException.php';
require_once 'OutOfStockException.php';
require_once 'InvalidQuantityException.php';

// Lire l'entrée
$productName = trim(fgets(STDIN));
$quantity = intval(trim(fgets(STDIN)));

// TODO: Utiliser try-catch pour gérer le traitement de la commande
// À l'intérieur du bloc try :
//   - Si quantity < 1, lancer InvalidQuantityException
//   - Si quantity > 100, lancer OutOfStockException
//   - Sinon, afficher "Order placed: [quantity]x [productName]"
//
// Attraper InvalidQuantityException en premier :
//   - Afficher "Quantity error: [message] (value: [quantity])" en utilisant getMessage() et getQuantity()
//
// Attraper OutOfStockException :
//   - Afficher "Stock error: [message] (product: [productName])" en utilisant getMessage() et getProductName()

?>