חריגות ב-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.

מה אובייקט חריגה מכיל

כל חריגה נושאת הודעה, קוד שלם, את הקובץ והשורה שבהם היא נוצרה, ו-stack trace. הבנאי מקבל ($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. ה-trace מפרט את הקריאות שהובילו לשם (#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 חשופה, כך שקורא לעולם לא ייאלץ לתפוס הכול כדי לטפל במקרה אחד.