تسلسل الاستثناءات المخصصة

جزء من قسم Object Oriented Programming في رحلة PHP على Coddy — الدرس 67 من 91.

بينما تغطي فئات الاستثناءات المضمنة في PHP السيناريوهات الشائعة، غالباً ما تحتاج التطبيقات الحقيقية إلى أنواع أخطاء أكثر تحديداً. يتيح لك إنشاء تسلسل هرمي مخصص للاستثناءات تعريف استثناءات تتوافق مع مجالك والتقاطها بمستويات مختلفة من التحديد.

لإنشاء استثناء مخصص، ما عليك سوى توسيع فئة Exception أو إحدى فئاتها الفرعية:

<?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;
    }
}

لاحظ كيف أن InsufficientFundsException يقوم بـ extends لـ PaymentException، وليس Exception مباشرة. هذا ينشئ تسلسلاً هرمياً حيث يمكنك التقاط جميع الاستثناءات المتعلقة بالدفع باستخدام كتلة catch واحدة، أو معالجة استثناءات محددة بشكل فردي.

يمكن أن تتضمن الاستثناءات المخصصة خصائص وطرقًا إضافية ذات صلة بالخطأ. هنا، توفر getShortfall() معلومات مفيدة لا يمكن للاستثناء العام تقديمها:

<?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;
    }
}

إن التسلسل الهرمي للاستثناءات المصمم جيداً يجعل الكود الخاص بك أكثر قابلية للصيانة. عند التقاط الاستثناءات، يمكنك أن تكون عاماً أو محدداً حسب الحاجة، كما تحمل كائنات الاستثناء نفسها سياقاً ذا معنى حول الخطأ الذي حدث.

التحدي

سهل

لنقم ببناء نظام لمعالجة الطلبات مع تسلسل هرمي للاستثناءات المخصصة (custom exception hierarchy) يتعامل مع أنواع مختلفة من فشل الطلبات. ستقوم بإنشاء استثناءات تحمل سياقاً ذا معنى حول الخطأ الذي حدث، مما يجعل معالجة الأخطاء أكثر دقة وإفادة.

ستقوم بتنظيم الكود الخاص بك عبر أربعة ملفات:

OrderException.php — أنشئ فئة أساسية باسم OrderException ترث من Exception. تعمل هذه الفئة كأب لجميع الاستثناءات المتعلقة بالطلبات، مما يسمح لك بالتقاط أي مشكلة في الطلب باستخدام كتلة catch واحدة عند الحاجة.
OutOfStockException.php — أنشئ فئة OutOfStockException ترث من OrderException. يجب أن يقبل هذا الاستثناء اسم المنتج والكمية المطلوبة في منشئ الفئة (constructor). استخدم خاصية constructor promotion لهذه الخصائص الخاصة (private). استدعِ منشئ الفئة الأب برسالة بالتنسيق "[productName] is out of stock (requested: [quantity])". أضف طريقة getProductName(): string تعيد اسم المنتج.
InvalidQuantityException.php — أنشئ فئة InvalidQuantityException ترث من OrderException. يجب أن يقبل هذا الاستثناء قيمة الكمية في منشئه باستخدام constructor promotion كخاصية خاصة (private). استدعِ منشئ الفئة الأب بالرسالة "Invalid quantity: [quantity]". أضف طريقة getQuantity(): int تعيد قيمة الكمية.
main.php — قم بتضمين ملفات الاستثناءات الثلاثة جميعها. ستتلقى مدخلين: اسم المنتج والكمية (كسلسلة نصية تحتاج إلى تحويلها إلى عدد صحيح).
بناءً على قيمة الكمية، قم برمي الاستثناء المناسب:
- إذا كانت الكمية أقل من 1، قم برمي InvalidQuantityException
- إذا كانت الكمية أكبر من 100، قم برمي OutOfStockException (لمحاكاة عدم كفاية المخزون)
- خلاف ذلك، اطبع "Order placed: [quantity]x [productName]"
التقط الاستثناءات باستخدام التسلسل الهرمي. أولاً، التقط InvalidQuantityException واطبع "Quantity error: [message] (value: [quantity])" باستخدام رسالة الاستثناء وطريقة getQuantity(). ثم التقط OutOfStockException واطبع "Stock error: [message] (product: [productName])" باستخدام رسالة الاستثناء وطريقة getProductName().

يتيح لك هذا التسلسل الهرمي التعامل مع استثناءات محددة بشكل فردي مع الاحتفاظ بخيار التقاط جميع المشكلات المتعلقة بالطلبات من خلال الفئة الأساسية OrderException. توفر الطرق المخصصة في كل استثناء سياقاً لا يمكن للاستثناء العام تقديمه.

ورقة مرجعية

قم بإنشاء استثناءات مخصصة عن طريق توسيع فئة Exception أو فئاتها الفرعية:

<?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;
    }
}

يمكن للاستثناءات المخصصة أن تشكل تسلسلاً هرمياً من خلال توسيع استثناءات مخصصة أخرى. يتيح ذلك التقاط الاستثناءات بمستويات مختلفة من التحديد - التقاط جميع الاستثناءات المتعلقة بالدفع باستخدام PaymentException، أو التعامل مع استثناءات محددة مثل InsufficientFundsException بشكل فردي.

يمكن أن تتضمن الاستثناءات المخصصة خصائص وطرقاً (methods) إضافية لتوفير سياق حول الخطأ:

<?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;
    }
}

استخدم ترقية المنشئ (constructor promotion) لتعريف الخصائص مباشرة في معاملات المنشئ. استدعِ parent::__construct() لتعيين رسالة الاستثناء.

جرّب بنفسك

<?php
// تضمين كافة ملفات الاستثناءات
require_once 'OrderException.php';
require_once 'OutOfStockException.php';
require_once 'InvalidQuantityException.php';

// قراءة المدخلات
$productName = trim(fgets(STDIN));
$quantity = intval(trim(fgets(STDIN)));

// TODO: استخدم try-catch لمعالجة عملية الطلب
// داخل كتلة try:
//   - إذا كانت الكمية (quantity) أقل من 1، قم برمي InvalidQuantityException
//   - إذا كانت الكمية (quantity) أكبر من 100، قم برمي OutOfStockException
//   - خلاف ذلك، اطبع "Order placed: [quantity]x [productName]"
//
// التقط InvalidQuantityException أولاً:
//   - اطبع "Quantity error: [message] (value: [quantity])" باستخدام getMessage() و getQuantity()
//
// التقط OutOfStockException:
//   - اطبع "Stock error: [message] (product: [productName])" باستخدام getMessage() و getProductName()

?>