Laravel İle Merkezi Bir Hata Yönetimi Ve Loglama Sistemi Nasıl Yapılır?

Ön Hazırlık ve Gereksinimler

Bu rehberi uygulamak için sisteminizde PHP 8.3 veya üzeri bir sürümün ve Laravel 11/12 framework'ünün kurulu olması gerekmektedir. Hata yönetimi süreçlerinde verimliliği artırmak için ayrıca bir log yönetim aracı (Sentry, Flare veya ELK Stack gibi) kullanmanız önerilir.

• PHP 8.3+ yüklü bir geliştirme ortamı.
• Laravel 11+ kurulu bir proje.
• Composer paket yöneticisine erişim.
• Hataları takip etmek için bir merkezi log servisi hesabı (isteğe bağlı).

Laravel Handler Sınıfını Özelleştirme

Laravel'de tüm hatalar app/Exceptions/Handler.php (veya Laravel 11+ yapısında bootstrap/app.php) dosyası üzerinden yönetilir. Hataları merkezi bir noktada toplamak için öncelikle bu dosyada özel bir raporlama mantığı kurmalıyız. Bu, tüm uygulamanın hata yönetim politikasını belirlediğimiz yerdir.

Aşağıdaki kod örneği, belirli bir hata türünü yakalayarak bunu merkezi log sistemimize nasıl gönderebileceğimizi göstermektedir:

// bootstrap/app.php içerisinde hata yönetimi yapılandırması
return Application::configure(basePath: dirname(__DIR__))
    ->withExceptions(function (Exceptions $exceptions) {
        $exceptions->report(function (Throwable $e) {
            // Hataları merkezi log servisine gönder
            if (app()->bound('sentry')) {
                app('sentry')->captureException($e);
            }
        });
    })->create();

Bu yapılandırma, uygulamanızda gerçekleşen her Throwable hatasını yakalar. Neden bu yöntemi kullanıyoruz? Çünkü her controller veya service içerisinde try-catch blokları yazmak yerine, global bir yakalama mekanizması ile kod tekrarını önlüyoruz.

Özel Hata Sayfaları ve Kullanıcı Deneyimi

Kullanıcıların teknik hata kodlarını görmesi hem güvenlik riski oluşturur hem de profesyonel bir görüntü sergilemez. Laravel'de HTTP hatalarını merkezi olarak ele alarak kullanıcıya daha dostane mesajlar gösterebilirsiniz. Bunun için render yöntemini kullanırız.

// bootstrap/app.php içerisinde render özelleştirmesi
$exceptions->render(function (NotFoundHttpException $e, Request $request) {
    if ($request->is('api/*')) {
        return response()->json([
            'message' => 'İstediğiniz kaynak bulunamadı.',
            'status' => 404
        ], 404);
    }

    return response()->view('errors.404', [], 404);
});

Bu kod bloğu, API istekleri ile web arayüzü isteklerini ayırarak kullanıcıya uygun formatta hata mesajı dönülmesini sağlar. Güvenlik açısından, üretim ortamında (production) hata detaylarını asla kullanıcıya göstermemelisiniz.

Log Kanallarını Yapılandırma

Laravel, config/logging.php dosyası üzerinden çoklu log kanalları sunar. Merkezi bir sistem için hataları sadece yerel dosyalara değil, uzak bir sunucuya veya bir veritabanına da yazmalısınız. Aşağıda, özel bir "merkezi" log kanalı oluşturma örneği yer almaktadır.

// config/logging.php içerisine eklenecek yapı
'channels' => [
    'centralized' => [
        'driver' => 'daily',
        'path' => storage_path('logs/centralized.log'),
        'level' => 'error',
        'days' => 14,
    ],
],

Bu yapılandırma, sadece 'error' seviyesindeki hataların 14 gün boyunca tutulmasını sağlar. Günlük (daily) loglama, log dosyalarının aşırı büyümesini engelleyerek disk alanını korur ve logların yönetilebilir kalmasını sağlar.

Hata Yönetimi Yöntemlerinin Karşılaştırılması

Özel Hata Sınıfları Oluşturma

Uygulamanızda iş mantığı hatalarını (örneğin: "Yetersiz Bakiye") yönetmek için özel exception sınıfları oluşturmak, kodunuzun okunabilirliğini artırır. Bu sınıflar, hatanın nerede ve neden oluştuğunu daha net ifade eder.

namespace App\Exceptions;

use Exception;

class InsufficientBalanceException extends Exception
{
    public function report()
    {
        // Bu hata oluştuğunda özel loglama yap
        logger()->warning('Kullanıcı bakiye yetersizliği yaşadı: ' . $this->getMessage());
    }
}

Bu sınıfı fırlattığınızda (throw new InsufficientBalanceException()), Laravel otomatik olarak report metodunu çalıştıracaktır. Bu, hata yönetimini nesne yönelimli programlama prensiplerine uygun hale getirir.

Kritik Güvenlik Uyarısı: Hata logları içerisinde asla kullanıcı şifreleri, kredi kartı bilgileri veya kişisel verileri (PII) düz metin olarak kaydetmeyin. Logları her zaman maskeleyerek veya filtreleyerek tutun.

Sıkça Sorulan Sorular

Log dosyalarım çok hızlı büyüyor, ne yapmalıyım?

Laravel'in daily log sürücüsünü kullanın ve config/logging.php dosyasında days parametresini optimize edin. Ayrıca log seviyesini debug yerine error olarak ayarlamak kayıt sayısını azaltacaktır.

Merkezi loglama için hangi servisi önerirsiniz?

Sentry, Laravel ile entegrasyonu en kolay olan ve hata takibinde detaylı izleme (stack trace) sunan popüler bir araçtır. Ancak gizlilik öncelikli ise ELK (Elasticsearch, Logstash, Kibana) yığınını kendi sunucunuza kurabilirsiniz.

API hatalarını nasıl daha profesyonel yönetebilirim?

Laravel'in JsonResource yapısını kullanarak hata yanıtlarını standart bir JSON formatına (örneğin: { "error": { "code": 400, "message": "..." } }) dönüştürerek API tüketicilerine tutarlı bir arayüz sunabilirsiniz.

Hata yakalarken performans kaybı yaşar mıyım?

Hata yakalama (exception handling) süreci, sadece hata oluştuğunda tetiklenir. Normal akışta performans etkisi ihmal edilebilir düzeydedir. Ancak yoğun loglama operasyonlarını asenkron (Queue) olarak yapmak performansı korur.

Production ortamında hata detaylarını nasıl gizlerim?

.env dosyanızdaki APP_DEBUG değerini false yaparak hata detaylarının kullanıcıya gösterilmesini engelleyebilirsiniz. Bu, uygulamanızın iç yapısının dışarıdan görünmesini engeller.

Sorumluluk Reddi: Bu makalede paylaşılan kod örnekleri eğitim amaçlıdır. Uygulamanızın canlı ortamına almadan önce mutlaka test ortamında doğrulama yapın. Güvenlik yapılandırmaları projenin özel ihtiyaçlarına göre değişiklik gösterebilir.

Hata Yönetiminde İleri Seviye İzleme: Slack Bildirim Entegrasyonu

Hataları sadece log dosyalarına yazmak, özellikle kritik üretim ortamlarında yeterli olmayabilir. Bir hata meydana geldiğinde geliştirici ekibinin anında haberdar olması, çözüm süresini (MTTR - Mean Time To Recovery) ciddi oranda düşürür. Laravel'in sunduğu Log facade yapısını kullanarak, belirli bir hata seviyesinin üzerindeki durumları doğrudan Slack kanalınıza gönderebilirsiniz.

Bunu yapmak için app/Exceptions/Handler.php dosyanızdaki register metodunu şu şekilde güncelleyebilirsiniz:

use Illuminate\Support\Facades\Log;
use Throwable;

public function register(): void
{
    $this->reportable(function (Throwable $e) {
        if ($this->shouldReport($e)) {
            Log::channel('slack')->critical('Kritik Sistem Hatası: ' . $e->getMessage(), [
                'url' => request()->fullUrl(),
                'user_id' => auth()->id() ?? 'Giriş yapılmamış',
                'trace' => $e->getTraceAsString()
            ]);
        }
    });
}

Bu yapılandırmanın çalışması için config/logging.php dosyanızda slack kanalının tanımlı olduğundan ve LOG_SLACK_WEBHOOK_URL değişkeninin .env dosyanızda tanımlandığından emin olun.

Hataları Test Etmek: Exception Handling Testleri

Yazdığınız hata yönetimi mekanizmasının doğru çalışıp çalışmadığını anlamak için birim testler yazmak en güvenli yoldur. Laravel'in withoutExceptionHandling() metodunu kullanarak hata yönetiminin devre dışı bırakıldığı durumları veya belirli bir exception'ın fırlatılıp fırlatılmadığını kolayca kontrol edebilirsiniz.

Aşağıdaki örnek, bir API endpoint'inin yetkisiz erişim durumunda doğru hata kodunu döndürüp döndürmediğini test eder:

public function test_unauthorized_access_returns_403()
{
    $response = $this->getJson('/api/admin/dashboard');

    $response->assertStatus(403)
             ->assertJson([
                 'message' => 'Bu işlem için yetkiniz bulunmamaktadır.'
             ]);
}

Bu testler, ileride yapacağınız kod değişikliklerinde hata yönetim mekanizmanızın bozulmadığından emin olmanızı sağlar. Özellikle Handler.php üzerinde yaptığınız özelleştirmelerin, farklı hata türleri (404, 403, 500) için beklenen JSON yanıtlarını üretip üretmediğini test etmek, uygulamanızın profesyonelliğini artırır.

Performans İçin Hata Yönetimi Optimizasyonu

Hata yönetimi sırasında veritabanına veya harici servislere (Slack, Sentry, vb.) çok fazla veri göndermek, uygulamanın yanıt süresini (latency) artırabilir. Bu durumu engellemek için "Hata Kuyruklama" (Error Queuing) stratejisini benimsemelisiniz.

• Asenkron İşleme: Logları veya bildirimleri doğrudan ana istek döngüsü içinde değil, Laravel'in Queue yapısını kullanarak arka planda işleyin.
• Hata Filtreleme: config/logging.php içerisinde sadece error ve critical seviyesindeki hataları dış servislere göndererek gereksiz trafikten kaçının.
• Veri Kısıtlama: Loglanan hata verisi içerisinde hassas kullanıcı bilgilerini (şifre, kredi kartı vb.) mutlaka maskeleyin. Laravel'in dontReport dizisi bu konuda size yardımcı olacaktır.

protected $dontReport = [
    \Illuminate\Auth\AuthenticationException::class,
    \Illuminate\Validation\ValidationException::class,
];

Bu kısıtlamalar, log dosyalarınızın gereksiz şişmesini engellerken, sistemin performansını korumanıza yardımcı olur.

Sonuç

Laravel ile merkezi bir hata yönetimi kurmak, uygulamanızın sürdürülebilirliği için atacağınız en önemli adımlardan biridir. Bu rehberde öğrendiğiniz global handler yapılandırması, özel exception sınıfları ve log kanalları ile artık hataları daha kontrollü bir şekilde yönetebilirsiniz. Bir sonraki adım olarak, bu logları bir bildirim sistemiyle (Slack veya Email) entegre ederek kritik hatalardan anında haberdar olmayı deneyebilirsiniz.