İçeriğe geç
Muhammet Şafak
en
Diller 4 dk okuma

PHP'de İstisnalar ve Hata Yönetimi

PHP'de istisnalar (exception) ve hata yönetimi: try-catch-finally yapıları, birden fazla catch bloğu, özel istisnalar, global handler ve error_reporting.

Kısaca

PHP, motorun ürettiği hatalarla bilerek fırlattığınız istisnaları ayırır; PHP 7'den beri ikisi de Throwable arayüzü altındadır. try-catch-finally, çoklu catch, özel istisnalar, global handler, hata seviyeleri ve @ operatörünün neden tuzak olduğu.

CRT ekranda local.ERROR: Uncaught custom exception: Could not connect to database log satırı, altında try / catch / finally bloğu

PHP’de hata yönetimi iki farklı mekanizma üzerinden yürür: hatalar (error) ve istisnalar (exception). İkisi arasındaki farkı anlamak, sadece teknik bir ayrıntı değil — nerede ne kullandığınız, uygulamanızın ne kadar öngörülebilir davrandığını doğrudan etkiliyor.

Hata (error), PHP motorunun tetiklediği bir durumdur: tanımsız bir değişken, bölünemez sıfır, mevcut olmayan bir fonksiyon çağrısı. İstisna ise sizin veya kullandığınız kütüphanenin bilerek fırlattığı, çağrı yığıtı boyunca taşınan ve yakalanabilir bir nesnedir. PHP 7 ile birlikte bu iki dünya Throwable arayüzü altında büyük ölçüde birleşti; artık Error sınıfı da catch edilebilir. PHP kılavuzu bunu şöyle tanımlıyor: “Throwable is the base interface for any object that can be thrown via a throw statement, including Error and Exception.” Ama bu birleşme zihinsel modeli değiştirmiyor: hataları yakalamak çoğunlukla bir güvenlik ağı kurmak içindir, istisnalar ise iş akışının bir parçasıdır.

try-catch-finally

Temel yapı her dilde benzer; PHP’de şöyle görünür:

function bolme(int $bolunen, int $bolen): float
{
    if ($bolen === 0) {
        throw new InvalidArgumentException("Sıfıra bölme.");
    }
    return $bolunen / $bolen;
}

try {
    echo bolme(10, 2) . "\n"; // 5
    echo bolme(10, 0) . "\n"; // exception fırlatılır
} catch (InvalidArgumentException $e) {
    echo "Geçersiz argüman: " . $e->getMessage() . "\n";
} finally {
    echo "Her durumda çalışır.\n";
}

Çıktı:

5
Geçersiz argüman: Sıfıra bölme.
Her durumda çalışır.

Birkaç noktanın üzerinde durmak istiyorum.

InvalidArgumentException kullandım — Exception değil. PHP’nin SPL kütüphanesi anlamlı bir hiyerarşi sunuyor: RuntimeException, LogicException, InvalidArgumentException, OutOfRangeException gibi. Doğrudan Exception fırlatmak, catch tarafında filtreleme imkânı vermez; “ne olduğu belli olmayan bir şey oldu” demiş olursunuz. Doğru exception türünü seçmek, çağıranın hatayı anlamlı biçimde ele almasını sağlar.

finally bloku istisna yakalanıp yakalanmadığından bağımsız çalışır. Tipik kullanım: veritabanı bağlantısını kapatmak, kilit serbest bırakmak, geçici dosyayı silmek gibi temizlik işlemleri. finally içinde return veya yeni bir throw kullanmak olası; ama bu noktada kodu takip etmek güçleşiyor — dikkatli olmakta fayda var.

Bir try bloğunun birden fazla catch bloğu olabilir mi?

Bir try bloğuna birden fazla farklı tipte exception için catch yazabilirsiniz:

try {
    $sonuc = veritabanindenCek($id);
} catch (NotFoundException $e) {
    return null; // kayıt yok, normal durum
} catch (DatabaseException $e) {
    logger()->error($e->getMessage());
    throw new ServiceException("Veri alınamadı.", 0, $e);
}

Buradaki yaklaşım bilinçli: NotFoundException sessizce null döndürüyor çünkü “kayıt yok” bir hata değil, beklenen bir sonuç. DatabaseException ise bir katman yukarı, daha genel bir exception olarak yeniden fırlatılıyor ve orijinal exception previous parametresiyle korunuyor. Bu, stack trace’i kaybetmeden soyutlama yapmanın standart yolu.

PHP 7.1’den itibaren birden fazla exception türünü tek catch bloğunda tutmak da mümkün. PHP 7.1 geçiş kılavuzu bunu şöyle söylüyor: “Multiple exceptions per catch block may now be specified using the pipe character (|).”

catch (NotFoundException | InvalidArgumentException $e) {
    // iki türü aynı şekilde ele al
}

Özel exception sınıfları

Kendi exception sınıflarınızı yazmak, uygulamanızın hata dilini zenginleştirir. Minimal bir örnek:

class PaymentFailedException extends RuntimeException
{
    private string $transactionId;

    public function __construct(
        string $transactionId,
        string $message = '',
        ?\Throwable $previous = null
    ) {
        $this->transactionId = $transactionId;
        parent::__construct($message, 0, $previous);
    }

    public function getTransactionId(): string
    {
        return $this->transactionId;
    }
}

Bu sınıfı catch eden kod $e->getTransactionId()’ye erişebilir. Log kaydına, alerting sistemine veya kullanıcıya dönen yanıta doğrudan bağlayabileceğiniz somut bir bağlam var.

Özellikle kütüphane yazarken, domain’inize özgü bir exception hiyerarşisi kurmak iyi bir pratik. Kütüphanenizin ürettiği tüm exceptionlar tek bir base exception’dan türerse, tüketici gerektiğinde hepsini tek catch ile yakalayabilir.

Global exception handler

Yakalanmamış exceptionlar için set_exception_handler() ile bir global handler tanımlayabilirsiniz:

set_exception_handler(function (\Throwable $e): void {
    logger()->critical($e->getMessage(), [
        'file' => $e->getFile(),
        'line' => $e->getLine(),
        'trace' => $e->getTraceAsString(),
    ]);
    http_response_code(500);
    echo json_encode(['error' => 'Beklenmeyen bir hata oluştu.']);
    exit(1);
});

Laravel, Symfony gibi framework’ler bunu zaten kendi Handler mekanizmalarıyla yönetiyor. Bare PHP ile çalışıyorsanız veya küçük bir kütüphane yazıyorsanız bu handler kritik.

Hata seviyeleri ve error_reporting

PHP’nin kendi hata sistemi ayrı bir boyut. Geliştirme ortamında görmek istediğiniz hata seviyelerini açık tutmak, production’da ise hataları log’a yönlendirip kullanıcıya göstermemek temel kural. php.ini üzerinden yapılandırmak tercih edilmeli; ama bazı paylaşımlı hosting ortamlarında bu erişim olmadığında error_reporting() ve ini_set() çalışma zamanında devreye girer:

// Geliştirme ortamı: her şeyi göster
error_reporting(E_ALL);
ini_set('display_errors', '1');

// Production: hataları gösterme, logla
error_reporting(E_ALL);
ini_set('display_errors', '0');
ini_set('log_errors', '1');
ini_set('error_log', '/var/log/php-errors.log');

PHP’nin hata seviyeleri bir bitmap yapısına sahiptir:

SabitDeğerAçıklama
E_ERROR1Ölümcül çalışma zamanı hatası; yürütme durur.
E_WARNING2Ölümcül olmayan çalışma zamanı uyarısı.
E_PARSE4Sözdizimi hatası; çözümleyici üretir.
E_NOTICE8Olası sorun bildirimi; tanımsız değişken gibi.
E_STRICT2048İleriye dönük uyumluluk önerileri.
E_ALL32767 (PHP 8.4’ten itibaren 30719)Tüm hata ve uyarılar.

Bu seviyeleri bit operatörleriyle birleştirip çıkarabilirsiniz:

error_reporting(E_ALL & ~E_NOTICE & ~E_STRICT);

@ operatöründen neden kaçınmalı?

PHP’de @ operatörü, önüne konduğu ifadenin ürettiği hataları bastırır (PHP 8.0’dan beri ölümcül hataları artık susturmaz: “The @ operator will no longer silence fatal errors (E_ERROR, E_CORE_ERROR, E_COMPILE_ERROR, E_USER_ERROR, E_RECOVERABLE_ERROR, E_PARSE).”). Teknik olarak çalışır; pratik olarak büyük bir kötü pratiktir.

// Yapmayın
echo @$tanimsizDegisken;

// Yapın
echo $tanimsizDegisken ?? '';

@ operatörü bir sorunu gizler, çözmez. Gerçek bir hata sessizce geçer; debug sırasında saatlerce kayıp yaşarsınız. Xdebug’ın xdebug.scream ayarıyla @ devre dışı bile bırakılabilir durumda; Xdebug belgeleri şöyle diyor: “If this setting is 1, then Xdebug will disable the @ (shut-up) operator so that notices, warnings and errors are no longer hidden.” Null coalescing (??), isset(), ya da doğru exception yönetimi her zaman daha temiz bir seçenek.


PHP 7 ve sonrası, exception yönetimini ciddi ölçüde olgunlaştırdı. Throwable birleşimi, previous parametresiyle exception zincirleme, union catch blokları bunların bir kısmı. Ama temel fikir değişmedi: bir exception, “beklenmedik değil, öngörülemeyen” durumu temsil eder. Öngörebildiğinizi if/else ile halledersiniz; öngöremediğinizi exception hiyerarşisiyle sarıp anlamlı bir şekilde iletirsiniz. Bu ayrımı zihinsel model olarak benimsemek, catch bloklarının neyi yakalayıp ne yapacağını netleştiriyor.


Kaynaklar

Sık sorulanlar

6 soru

  • PHP'de error ile exception arasındaki fark nedir?

    Error, doğrudan PHP motorunun tetiklediği bir durumdur: tanımsız değişken, sıfıra bölme gibi. Exception ise sizin ya da bir kütüphanenin bilerek fırlattığı, çağrı yığınında yukarı taşınan ve yakalanabilen bir nesnedir. PHP 7 ile bu iki dünya büyük ölçüde Throwable arayüzü altında birleşti; yani Error da artık yakalanabilir.

  • Bir try bloğunun birden fazla catch bloğu olabilir mi?

    Evet, tek bir try bloğuna farklı exception türleri için birden fazla catch yazabilirsiniz. Örneğimde kayıt bulunamadı exception'ı null döndürür, çünkü kaydın olmaması beklenen bir sonuçtur; veritabanı exception'ı ise orijinali previous parametresiyle korunarak daha genel bir exception olarak yeniden fırlatılır. PHP 7.1'den beri birden fazla exception türünü tek catch bloğunda pipe karakteriyle de birleştirebilirsiniz.

  • finally bloğu ne işe yarar?

    Bir exception yakalansa da yakalanmasa da çalışır. Tipik kullanımı veritabanı bağlantısını kapatmak, bir kilidi bırakmak ya da geçici dosyayı silmektir. finally içinde return ya da yeni bir throw kullanmak mümkündür ama kod takip edilmesi zor hâle gelir; dikkatli olun.

  • Neden özel exception sınıfları yazılır?

    Uygulamanızın hata sözlüğünü zenginleştirirler. Sınıfınızı yakalayan kod, örneğin bir işlem kimliği gibi somut bağlamı okuyup log kayıtlarına, uyarı sistemlerine ya da kullanıcıya dönen yanıta aktarabilir. Kütüphane yazarken tüm exception'lar tek bir temel exception'dan türüyorsa, kullanan taraf hepsini tek catch ile yakalayabilir.

  • Hatalar geliştirmede ve production'da nasıl gösterilmeli?

    Geliştirmede tüm hata seviyeleri görünür kalsın. Production'da hatalar loga yazılsın, kullanıcıya asla gösterilmesin. Bunu php.ini üzerinden ayarlamak tercih edilir; o erişimin olmadığı ortamlarda error_reporting() ve ini_set() çalışma zamanında devreye girebilir.

  • @ operatöründen neden kaçınmalı?

    Sorunu çözmez, gizler. Gerçek bir hata sessizce geçer ve saatlerce hata ayıklarsınız. PHP 8.0'dan beri fatal hataları artık susturmuyor, ama yine de bir anti-pattern olmayı sürdürüyor. Null coalescing, isset() ya da düzgün exception yönetimi her zaman daha temiz seçimdir.

Bu konudaki deneyler

30'u aşkın PHP paketi hem tek başına hem birlikte kullanılabilir kaldı; Lab kaydı kapandı, paketler bakımda. Nasıl yapıldığının yapım notları.

Şu an ne yapıyor

30'u aşkın paketlik bir PHP kütüphane ailesi: Router, Database, Cache, Mailer, Socket ve diğerleri hem tek başına hem birlikte çalışıyor, hepsi Composer/Packagist üzerinden MIT lisansıyla dağıtılıyor. Framework'e bağlanmadan parça kullanmak isteyen PHP geliştiricisi bugün kurabilir.

Open-Source PHP Composer PHPUnit
Ocak 2021 — Ağustos 2022

Yorumlar

Yorum yapmak için GitHub hesabınızla giriş yapmanız yeterli. Yorumlar GitHub Discussions üzerinde saklanır.

İlgili Yazılar

Sitede Ara

Yazı, proje ve sayfalarda arama yapmak için yazmaya başlayın.

Esc ile kapat Pagefind ile güçlendirildi