PHP İstisnalar: throw ve Özel İstisna Sınıfları

PHP'de bir istisnayı throw new Exception('message'); ile fırlatırsınız. Çalışma o satırda durur ve istisnanın türünü kabul eden en yakın catch bloğuna atlar; orada $e->getMessage() mesajı döndürür. Çağıranların sorunları ayırt edebilmesi için InvalidArgumentException gibi belirli bir sınıf kullanı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";
}

Bir istisna bir nesnedir. throw onu çağrı yığınında eşleşen bir catch bloğuna sahip ilk çağırana kadar yukarı iletir ve ne yapılacağına o çağıran karar verir; sorunu bulan fonksiyonun bunu bilmesi gerekmez. Yakalamanın işleyişi, finally ve birkaç türü yakalamak try catch sayfasında.

Bir istisna nesnesi neler içerir

Her istisna bir mesaj, bir tam sayı kodu, oluşturulduğu dosya ve satır ve bir yığın izi taşır. Yapıcı, hepsi isteğe bağlı olan ($message, $code, $previous) argümanlarını alır:

<?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() catch satırı değil, throw new satırıdır. İz oraya götüren çağrıları listeler (#0 /home/index.php(8): findOrder()); bu, bir hata bir logda göründüğünde genellikle ilk okunacak şeydir. İstisnayı bir dizgeye çevirmek (echo $e; veya (string) $e) hepsini PHP'nin standart biçiminde yazdırır.

Yerleşik istisna sınıfları

PHP, Standart PHP Kütüphanesinde (SPL) bir istisna sınıfları ailesiyle gelir. Sorunu adlandıran sınıfı fırlatmak kodunuzu daha okunur yapar ve çağıranların dar bir şekilde yakalamasını sağlar. Bunların hepsi Exception sınıfını genişletir:

InvalidArgumentException, DomainException, LengthException ve OutOfRangeException LogicException sınıfını genişletir; OutOfBoundsException, RangeException ve UnexpectedValueException ise RuntimeException sınıfını genişletir. Herhangi bir sınıfın üst sınıflarını kendiniz kontrol edebilirsiniz:

<?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 sınıfının üst sınıfı Exception değil Error sınıfıdır: aşağıdaki ikinci aileye aittir.

PHP'nin kendisinin fırlattığı hatalar

PHP 7'den beri, PHP 8'den beri ise çok daha fazla, PHP'nin kendi fonksiyonları ve operatörleri eskiden uyarı olan sorunlar için Error alt sınıfları fırlatır. Onları aynı şekilde yakalarsınız, ama catch (Exception $e) onlarla eşleşmez:

<?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 ve düz Error hepsi Error sınıfını genişletir. Her biri hatalı veriden çok çağıran koddaki bir bug'ı işaret eder; Exception ağacının dışında yaşamalarının nedeni budur. str_repeat(5, 2) ifadesini bir TypeError yapan declare(strict_types=1) satırıdır; o olmadan PHP 5 değerini "5" değerine çevirirdi.

Özel bir istisna sınıfı yazma

Çoğu zaman tek satırlık bir alt sınıf yeterlidir: sınıf adının kendisi anlamı taşır ve çağıranlar tam olarak o türü yakalayabilir. Yakalayanın veriye (hangi sipariş, hangi tutar) ihtiyacı olduğunda özellikler ekleyin ve mesajı parent::__construct() ile yukarı iletin:

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

Üst sınıfı dikkatle seçin: (düz Exception yerine) RuntimeException sınıfını genişletmek, RuntimeException yakalayan kodun sizinkini de ele alması demektir. Küçük bir hiyerarşi, yani altında belirli alt sınıflar olan kütüphane veya modül başına bir temel istisna, çağıranların "ödemelerden gelen her şeyi yakala" ile "yalnızca bu durumu yakala" arasında seçim yapmasını sağlar.

previous ile istisnaları zincirleme

Düşük seviyeli bir istisnayı yakalayıp daha üst seviyeli bir istisna fırlattığınızda orijinali üçüncü argüman olarak verin. Hiçbir şey kaybolmaz: getPrevious() kök nedene kadar geri gider.

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

Kullanıcı "customers.csv could not be imported" görür; zinciri izleyen log ise "row 2 has 2 columns" bilgisini de alır. Zincirlenmiş bir istisna hiç yakalanmazsa PHP'nin ölümcül hatası zincirin tamamını yazdırır: önce orijinal neden, sonra her sarmalayıcı bir Next satırının altında.

Bir ifade olarak throw

PHP 8.0'dan beri throw bir ifadedir, bu yüzden bir değer beklenen her yerde durabilir: ?? sonrasında, bir üçlü ifadede, bir ok fonksiyonunda. "Bunu al ya da başarısız ol" işlemini tek satır yapar:

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

Ne zaman fırlatmamalı

İstisnalar mevcut fonksiyonun ele alamadığı ve normal akışın beklemediği durumlar içindir. Hiçbir şey bulamayan bir arama, boş olan isteğe bağlı bir alan veya giriş yapmamış bir kullanıcı sıradan sonuçlardır: null, false veya boş bir dizi döndürün ve çağıranın kontrol etmesine izin verin; istisnaları devam etmenin yanlış olacağı durumlara saklayın.

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

İki alışkanlık daha istisna kodunu okunur tutar: bir istisnayı asla yalnızca yok saymak için yakalamayın (boş bir catch (Exception $e) {} bir sonraki gerçek bug'ı gizler) ve çıplak Exception yerine belirli sınıflar fırlatın, böylece bir çağıran tek bir durumu ele almak için asla her şeyi yakalamak zorunda kalmaz.