Hiérarchie d’exceptions personnalisée

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

Bien 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. La création d’une hiérarchie d’exceptions personnalisée vous permet de définir des exceptions correspondant à votre domaine et de les intercepter à différents niveaux de spécificité.

Pour créer une exception personnalisée, il suffit d’étendre 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 que InsufficientFundsException extends PaymentException, et non directement Exception. Cela crée une hiérarchie dans laquelle vous pouvez intercepter toutes les exceptions liées au paiement avec un seul bloc catch, ou traiter 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. Lorsque vous interceptez des exceptions, vous pouvez être aussi général ou précis que nécessaire, et les objets d’exception eux-mêmes fournissent 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 créerez des exceptions qui contiennent un contexte pertinent sur ce qui s’est mal passé, ce qui rendra 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 à toutes les exceptions liées aux commandes, ce qui vous permet d’intercepter tout problème de commande avec un seul bloc catch lorsque 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 des propriétés du 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 renvoie 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 du constructeur comme propriété privée. Appelez le constructeur parent avec le message "Invalid quantity: [quantity]". Ajoutez une méthode getQuantity(): int qui renvoie 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 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 (pour simuler un stock insuffisant)
- Sinon, affichez "Order placed: [quantity]x [productName]"
Interceptez les exceptions en utilisant la hiérarchie. Interceptez d’abord InvalidQuantityException et affichez "Quantity error: [message] (value: [quantity])" en utilisant le message de l’exception et sa méthode getQuantity(). Interceptez ensuite OutOfStockException et affichez "Stock error: [message] (product: [productName])" en utilisant le message de l’exception et sa méthode getProductName().

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

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, throw InvalidQuantityException
//   - Si quantity > 100, throw OutOfStockException
//   - Sinon, afficher "Order placed: [quantity]x [productName]"
//
// Catch InvalidQuantityException en premier :
//   - Afficher "Quantity error: [message] (value: [quantity])" en utilisant getMessage() et getQuantity()
//
// Catch OutOfStockException :
//   - Afficher "Stock error: [message] (product: [productName])" en utilisant getMessage() et getProductName()

?>