Laravel Queue Worker ve Horizon Kurulum Rehberi (2026)

Modern web uygulamalarında e-posta gönderimi, PDF faturası oluşturma, harici API çağrıları veya webhook bildirimleri gibi ağır işlemleri HTTP istek-yanıt döngüsünde bekletmek kullanıcı deneyimini doğrudan bozar. Laravel Queue (Kuyruk) mimarisi ve Laravel Horizon kontrol paneli, bu asenkron işleri arka planda güvenle ölçeklemenin standart yoludur.

Laravel Kuyruk Mimarisi Nasıl Çalışır?

Bir kullanıcı sitenizden sipariş verdiğinde; ödeme işlemi tamamlandıktan sonra müşteriye fatura üretilmesi, SMS gönderilmesi ve kargo entegrasyonuna veri aktarılması gerekir. Bu adımları doğrudan Controller içinde senkron çalıştırırsanız, sayfa yanıt süresi 4-8 saniyeye kadar uzayabilir.

Kuyruk mekanizması ile iş (Job) bir veri deposuna (Redis veya Veritabanı) serileştirilerek bırakılır ve kullanıcıya anında 200 OK yanıtı dönülür. Arka planda sürekli çalışan bir Queue Worker process'i bu işi sıradan alır ve bağımsız olarak yürütür.

Kuyruk Driver Karşılaştırması: Database vs. Redis

Production İçin Kritik artisan queue:work Parametreleri

Production ortamında ham php artisan queue:work komutu çalıştırmak tehlikelidir. Hata durumlarında sonsuz döngüye girmemek veya bellek sızıntısını önlemek için şu bayraklar mutlaka kullanılmalıdır:

• --tries=3: Bir iş hata aldığında maksimum 3 kez tekrar denenir, ardından failed_jobs tablosuna yazılır.
• --timeout=90: Bir iş 90 saniyeden uzun sürerse process güvenli şekilde sonlandırılır.
• --max-time=3600 & --max-jobs=1000: PHP process'i 1 saat veya 1000 iş sonrasında kendini yeniler (Memory Leak önleme).
• --memory=128: Worker belleği 128 MB'ı aşarsa graceful restart yapar.

Laravel Horizon Kurulumu ve Dashboard Güvenliği

Laravel Horizon, Redis kuyruklarınızı gerçek zamanlı grafiklerle izlemenizi, işleme sürelerini, throughput değerlerini ve başarısız işleri tek ekrandan yönetmenizi sağlar.

app/Providers/HorizonServiceProvider.php dosyasındaki gate() metodunu düzenleyerek yalnızca yetkili yöneticilerin /horizon paneline erişebilmesini sağlayın:

protected function gate(): void
{
    Gate::define('viewHorizon', function ($user) {
        return in_array($user->email, [
            'admin@siteniz.com',
            'dev@skyversal.com',
        ]);
    });
}

Supervisor Alternatifi: Skyversal PaaS'ta Kalıcı Process Tanımlama

Geleneksel bir Linux VPS üzerinde kuyruk çalıştırmak için Linux supervisor servisini yapılandırmak, dosya izinleri ayarlamak ve her deploy sonrası supervisorctl restart tetiklemek gerekir.

Skyversal PaaS üzerinde bu süreç tamamen otomatikleştirilmiştir. Panelinizdeki Proje Ayarları > Processes alanına girerek kuyruk komutunuzu tek satırda tanımlayabilirsiniz:

Sık Karşılaşılan Kuyruk Hataları ve Çözümleri