Exception PHP: throw dan Membuat Class Exception Sendiri

Kamu melempar exception di PHP dengan throw new Exception('message');. Eksekusi berhenti di baris itu dan melompat ke blok catch terdekat yang menerima tipe exception tersebut, dan di sana $e->getMessage() mengembalikan pesannya. Pakai class yang spesifik, seperti InvalidArgumentException, supaya pemanggil bisa membedakan setiap masalah.

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

Exception adalah objek. throw meneruskannya ke atas melalui call stack sampai ke pemanggil pertama yang punya catch yang cocok, dan pemanggil itulah yang memutuskan apa yang harus dilakukan; fungsi yang menemukan masalahnya tidak perlu tahu. Cara kerja menangkap exception, finally, dan menangkap beberapa tipe ada di halaman try catch.

Isi sebuah objek exception

Setiap exception membawa pesan, kode integer, file dan baris tempat ia dibuat, serta stack trace. Constructor-nya menerima ($message, $code, $previous), semuanya opsional:

<?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() adalah baris throw new, bukan baris catch. Trace-nya mencantumkan panggilan-panggilan yang mengarah ke sana (#0 /home/index.php(8): findOrder()), yang biasanya menjadi hal pertama yang dibaca saat sebuah error muncul di log. Mengubah exception menjadi string (echo $e; atau (string) $e) mencetak semuanya dalam format standar PHP.

Class exception bawaan

PHP menyertakan sekumpulan class exception di Standard PHP Library (SPL). Melempar class yang menamai masalahnya membuat kodemu lebih mudah dibaca dan memungkinkan pemanggil menangkap secara spesifik. Semua class ini meng-extend Exception:

InvalidArgumentException, DomainException, LengthException, dan OutOfRangeException meng-extend LogicException; OutOfBoundsException, RangeException, dan UnexpectedValueException meng-extend RuntimeException. Kamu bisa memeriksa induk dari class mana pun sendiri:

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

Induk TypeError adalah Error, bukan Exception: ia termasuk keluarga kedua, di bawah ini.

Error yang dilempar PHP sendiri

Sejak PHP 7, dan jauh lebih banyak sejak PHP 8, fungsi dan operator bawaan PHP melempar subclass Error untuk masalah yang dulunya hanya warning. Kamu menangkapnya dengan cara yang sama, tetapi catch (Exception $e) tidak akan cocok dengannya:

<?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, dan Error biasa semuanya meng-extend Error. Masing-masing lebih sering menandakan bug di kode pemanggil daripada data yang buruk, karena itulah mereka berada di luar pohon Exception. declare(strict_types=1) yang membuat str_repeat(5, 2) menjadi TypeError; tanpa itu, PHP akan mengonversi 5 menjadi "5".

Menulis class exception sendiri

Subclass satu baris sering kali sudah cukup: nama class-nya sendiri membawa makna, dan pemanggil bisa menangkap tepat tipe itu. Saat penangkapnya butuh data (pesanan yang mana, jumlah berapa), tambahkan property lalu teruskan pesannya ke atas dengan 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";
}

Pilih induknya dengan cermat: meng-extend RuntimeException (alih-alih Exception biasa) berarti kode yang menangkap RuntimeException juga menangani exception milikmu. Hierarki kecil, satu exception dasar per library atau modul dengan subclass spesifik di bawahnya, memberi pemanggil pilihan antara "tangkap semua dari modul pembayaran" dan "tangkap kasus yang ini saja".

Merangkai exception dengan previous

Saat kamu menangkap exception tingkat rendah lalu melempar exception tingkat yang lebih tinggi, berikan exception aslinya sebagai argumen ketiga. Tidak ada yang hilang: getPrevious() menelusuri kembali sampai ke akar penyebabnya.

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

Pengguna melihat "customers.csv could not be imported"; log, yang menelusuri rangkaiannya, juga mendapat "row 2 has 2 columns". Kalau exception yang dirangkai tidak pernah ditangkap, fatal error dari PHP mencetak seluruh rangkaiannya: penyebab asli lebih dulu, lalu setiap pembungkusnya di bawah baris Next.

throw sebagai ekspresi

Sejak PHP 8.0, throw adalah ekspresi, jadi bisa diletakkan di mana pun sebuah nilai diharapkan: setelah ??, di dalam ternary, di dalam arrow function. Dengan begitu, "ambil ini atau gagal" cukup satu baris:

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

Kapan tidak perlu melempar exception

Exception dipakai untuk situasi yang tidak bisa ditangani fungsi saat ini dan tidak diharapkan oleh alur normal. Pencarian yang tidak menemukan apa-apa, field opsional yang kosong, atau pengguna yang belum login adalah hasil yang biasa: kembalikan null, false, atau array kosong dan biarkan pemanggil memeriksanya, lalu simpan exception untuk kasus ketika melanjutkan program justru salah.

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

Dua kebiasaan lagi yang membuat kode exception tetap mudah dibaca: jangan pernah menangkap exception hanya untuk mengabaikannya (catch (Exception $e) {} yang kosong menyembunyikan bug sungguhan berikutnya), dan lempar class yang spesifik alih-alih Exception polos, supaya pemanggil tidak pernah terpaksa menangkap semuanya hanya untuk menangani satu kasus.