الاستثناءات في PHP: throw وأصناف الاستثناءات المخصصة

ترمي استثناءً في PHP بـ throw new Exception('message');. يتوقف التنفيذ عند ذلك السطر ويقفز إلى أقرب كتلة catch تقبل نوع الاستثناء، حيث تعيد $e->getMessage() الرسالة. استخدم صنفًا محددًا، مثل InvalidArgumentException، ليتمكن المستدعون من التمييز بين المشكلات.

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

الاستثناء كائن. تمرره throw صعودًا في مكدس الاستدعاءات إلى أول مستدعٍ لديه catch مطابقة، وذلك المستدعي يقرر ما يفعل؛ ولا تحتاج الدالة التي وجدت المشكلة إلى معرفة ذلك. وآلية الالتقاط وfinally والتقاط عدة أنواع موجودة في صفحة try catch.

ما يحتويه كائن الاستثناء

يحمل كل استثناء رسالة، ورمزًا صحيحًا، والملف والسطر اللذين أُنشئ فيهما، ومسار الاستدعاءات. يأخذ الباني ($message, $code, $previous)، وكلها اختيارية:

<?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() هو سطر throw new، لا سطر catch. ويسرد المسار الاستدعاءات التي أدت إلى هناك (#0 /home/index.php(8): findOrder())، وهو عادة أول ما يُقرأ حين يظهر خطأ في سجل. وتحويل الاستثناء إلى نص (echo $e; أو (string) $e) يطبعه كله بالتنسيق القياسي لـ PHP.

أصناف الاستثناءات المدمجة

تأتي PHP بعائلة من أصناف الاستثناءات في مكتبتها القياسية (SPL). ورمي الصنف الذي يسمّي المشكلة يجعل شيفرتك أوضح ويتيح للمستدعين الالتقاط بدقة. وكلها ترث Exception:

ترث InvalidArgumentException وDomainException وLengthException وOutOfRangeException الصنف LogicException؛ وترث OutOfBoundsException وRangeException وUnexpectedValueException الصنف RuntimeException. ويمكنك فحص آباء أي صنف بنفسك:

<?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 هو Error، لا Exception: فهو ينتمي إلى العائلة الثانية، أدناه.

الأخطاء التي ترميها PHP بنفسها

منذ PHP 7، وأكثر بكثير منذ PHP 8، ترمي دوال PHP وعواملها أصنافًا فرعية من Error لمشكلات كانت تحذيرات. تلتقطها بالطريقة نفسها، لكن catch (Exception $e) لن تطابقها:

<?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 وError العادي كلها Error. وكل منها يدل على خطأ في الشيفرة المستدعية أكثر مما يدل على بيانات سيئة، ولهذا تعيش خارج شجرة Exception. وdeclare(strict_types=1) هو ما يجعل str_repeat(5, 2) خطأ TypeError؛ ودونه ستحوّل PHP العدد 5 إلى "5".

كتابة صنف استثناء مخصص

كثيرًا ما يكفيك صنف فرعي من سطر واحد: اسم الصنف نفسه يحمل المعنى، ويستطيع المستدعون التقاط ذلك النوع بالضبط. وعندما يحتاج الملتقط إلى بيانات (أي طلب، أي مبلغ)، أضف خصائص ومرّر الرسالة صعودًا بـ 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";
}

اختر الأب بعناية: وراثة RuntimeException (بدل Exception العادي) تعني أن الشيفرة التي تلتقط RuntimeException تعالج استثناءك أيضًا. والتسلسل الهرمي الصغير، استثناء أساسي واحد لكل مكتبة أو وحدة مع أصناف فرعية محددة تحته، يتيح للمستدعين الاختيار بين «التقط كل شيء من المدفوعات» و«التقط هذه الحالة وحدها».

تسلسل الاستثناءات بـ previous

عندما تلتقط استثناءً منخفض المستوى وترمي استثناءً أعلى مستوى، مرّر الأصلي وسيطًا ثالثًا. لا يضيع شيء: تعود getPrevious() إلى السبب الجذري.

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

يرى المستخدم "customers.csv could not be imported"؛ ويحصل السجل، بالمرور على السلسلة، على "row 2 has 2 columns" أيضًا. وإذا لم يُلتقط استثناء متسلسل أبدًا، يطبع الخطأ الفادح في PHP السلسلة كلها: السبب الأصلي أولًا، ثم كل غلاف تحت سطر Next.

throw بوصفها تعبيرًا

منذ PHP 8.0، throw تعبير، لذا يمكن أن تقع حيثما تُتوقع قيمة: بعد ??، وفي العامل الثلاثي، وفي دالة سهمية. وتجعل «احصل على هذا أو افشل» سطرًا واحدًا:

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

متى لا ترمي

الاستثناءات للمواقف التي لا تستطيع الدالة الحالية معالجتها ولا يتوقعها المسار العادي. أما البحث الذي لا يجد شيئًا، أو الحقل الاختياري الفارغ، أو المستخدم غير المسجل دخوله، فنتائج عادية: أعِد null أو false أو مصفوفة فارغة ودع المستدعي يتحقق، واحتفظ بالاستثناءات للحالات التي يكون فيها المضي قدمًا خطأً.

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

عادتان أخريان تُبقيان شيفرة الاستثناءات مقروءة: لا تلتقط استثناءً لتتجاهله أبدًا (تخفي catch (Exception $e) {} الفارغة الخطأ الحقيقي التالي)، وارمِ أصنافًا محددة لا Exception المجردة، حتى لا يُجبر المستدعي أبدًا على التقاط كل شيء لمعالجة حالة واحدة.