Ngoại lệ trong PHP: throw và lớp exception tùy chỉnh

Bạn ném một ngoại lệ (exception) trong PHP bằng throw new Exception('message');. Việc thực thi dừng ở dòng đó và nhảy đến khối catch gần nhất nhận kiểu của ngoại lệ, nơi $e->getMessage() trả về thông báo. Hãy dùng một lớp cụ thể, như InvalidArgumentException, để nơi gọi phân biệt được các vấn đề.

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

Ngoại lệ là một đối tượng. throw đẩy nó ngược lên call stack đến nơi gọi đầu tiên có catch phù hợp, và nơi gọi đó quyết định phải làm gì; hàm phát hiện ra vấn đề không cần biết điều đó. Cách bắt ngoại lệ, finally và bắt nhiều kiểu cùng lúc có ở trang try catch.

Đối tượng ngoại lệ chứa gì

Mọi ngoại lệ đều mang theo một thông báo, một mã số nguyên, tệp và dòng nơi nó được tạo ra, cùng một stack trace. Hàm khởi tạo nhận ($message, $code, $previous), tất cả đều không bắt buộc:

<?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() là dòng chứa throw new, không phải dòng của catch. Trace liệt kê các lời gọi dẫn đến đó (#0 /home/index.php(8): findOrder()), thường là thứ đầu tiên cần đọc khi một lỗi xuất hiện trong log. Ép ngoại lệ thành chuỗi (echo $e; hoặc (string) $e) sẽ in ra tất cả theo định dạng chuẩn của PHP.

Các lớp exception có sẵn

PHP có sẵn một họ lớp exception trong Standard PHP Library (SPL). Ném đúng lớp gọi tên vấn đề giúp code dễ đọc hơn và cho phép nơi gọi bắt thật chính xác. Tất cả các lớp này đều kế thừa Exception:

InvalidArgumentException, DomainException, LengthException và OutOfRangeException kế thừa LogicException; OutOfBoundsException, RangeException và UnexpectedValueException kế thừa RuntimeException. Bạn có thể tự kiểm tra các lớp cha của bất kỳ lớp nào:

<?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 có lớp cha là Error, không phải Exception: nó thuộc họ thứ hai, ở bên dưới.

Các lỗi do chính PHP ném ra

Từ PHP 7, và càng nhiều hơn từ PHP 8, các hàm và toán tử của chính PHP ném ra lớp con của Error cho những vấn đề trước đây chỉ là cảnh báo. Bạn bắt chúng theo cùng một cách, nhưng catch (Exception $e) sẽ không khớp với chúng:

<?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 và Error thuần đều kế thừa Error. Mỗi lớp thường đánh dấu một bug trong code gọi hơn là dữ liệu xấu, đó là lý do chúng nằm ngoài cây Exception. Chính declare(strict_types=1) khiến str_repeat(5, 2) thành TypeError; nếu không có nó, PHP sẽ chuyển 5 thành "5".

Viết lớp exception tùy chỉnh

Một lớp con chỉ một dòng thường là đủ: chính tên lớp đã mang ý nghĩa, và nơi gọi có thể bắt đúng kiểu đó. Khi nơi bắt cần dữ liệu (đơn hàng nào, số tiền bao nhiêu), hãy thêm thuộc tính và chuyển thông báo lên bằng 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";
}

Hãy chọn lớp cha cẩn thận: kế thừa RuntimeException (thay vì Exception thuần) nghĩa là code nào bắt RuntimeException cũng xử lý luôn ngoại lệ của bạn. Một hệ thống phân cấp nhỏ, mỗi thư viện hoặc module có một ngoại lệ gốc và các lớp con cụ thể bên dưới, cho phép nơi gọi chọn giữa "bắt mọi thứ từ phần thanh toán" và "chỉ bắt đúng trường hợp này".

Nối chuỗi ngoại lệ với previous

Khi bạn bắt một ngoại lệ cấp thấp rồi ném một ngoại lệ cấp cao hơn, hãy truyền ngoại lệ gốc làm đối số thứ ba. Không có gì bị mất: getPrevious() lần ngược về nguyên nhân gốc.

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

Người dùng thấy "customers.csv could not be imported"; còn log, khi lần theo chuỗi, nhận thêm "row 2 has 2 columns". Nếu một ngoại lệ đã nối chuỗi không bao giờ được bắt, lỗi nghiêm trọng của PHP sẽ in cả chuỗi: nguyên nhân gốc trước, rồi đến từng lớp bọc dưới một dòng Next.

throw dưới dạng biểu thức

Từ PHP 8.0, throw là một biểu thức, nên nó có thể đặt ở bất kỳ đâu cần một giá trị: sau ??, trong toán tử ba ngôi, trong arrow function. Nhờ đó "lấy giá trị này hoặc báo lỗi" chỉ còn một dòng:

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

Khi nào không nên ném ngoại lệ

Ngoại lệ dành cho những tình huống mà hàm hiện tại không xử lý được và luồng chạy bình thường không lường trước. Một lần tìm kiếm không thấy gì, một trường không bắt buộc bị bỏ trống, hay một người dùng chưa đăng nhập đều là kết quả bình thường: hãy trả về null, false hoặc một mảng rỗng để nơi gọi tự kiểm tra, và giữ ngoại lệ cho những trường hợp mà chạy tiếp sẽ là sai.

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

Thêm hai thói quen giúp code xử lý ngoại lệ dễ đọc: đừng bao giờ bắt một ngoại lệ chỉ để bỏ qua nó (một catch (Exception $e) {} rỗng sẽ che giấu bug thật tiếp theo), và hãy ném các lớp cụ thể thay vì Exception trơn, để nơi gọi không bao giờ bị buộc phải bắt mọi thứ chỉ để xử lý một trường hợp.