Laravel Queue Worker’ları Nedir? Arka Plan İşleme Rehberi

Laravel'de queue worker'lar, e-posta gönderimi, resim işleme veya dış API çağrıları gibi uzun süren işleri kullanıcıyı bekletmeden arka planda çalıştırmanızı sağlar. Bu rehberde queue mantığı, worker kurulumu ve üretim ortamında dikkat edilmesi gerekenler adım adım anlatılıyor.

Queue (kuyruk) ve worker nedir?

Bir web isteği geldiğinde, kullanıcıyı saniyelerce bekletecek işlemleri (ör. 500 kişiye toplu e-posta gönderme) doğrudan istek içinde çalıştırmak kötü bir kullanıcı deneyimi yaratır. Laravel'in queue sistemi, bu tür işleri bir "iş" (job) olarak kuyruğa ekler; worker adı verilen ayrı bir arka plan süreci ise kuyruktan işleri alır. Birden fazla worker paralel çalışabileceği için bütün işlerin aynı sırada tamamlanacağını varsaymayın.

Hangi sürücüler (driver) kullanılabilir?

Temel kurulum adımları

Ek ayarlar Laravel 13.x belgesiyle kontrol edildi. Kendi sürümünüzü php artisan --version ile belirleyin. Database sürücüsünde jobs tablosu gerekir; migration yoksa 13.x için php artisan make:queue-table ile oluşturup migration’ı gözden geçirin.

1. .env dosyasında QUEUE_CONNECTION değerini seçtiğiniz sürücüye göre ayarlayın (ör. redis).
2. Bir job sınıfı oluşturun: php artisan make:job SendWelcomeEmail
3. Job içindeki handle() metoduna asıl iş mantığını yazın.
4. İşi kuyruğa göndermek için kod içinde SendWelcomeEmail::dispatch($user); kullanın.
5. Worker'ı başlatın: php artisan queue:work

Aşağıdaki sınıf bir iskelettir; mevcut hâli e-posta göndermez. Projenizdeki kullanıcı modeli ve e-posta servisini ekleyin.

<?php

namespace App\Jobs;

use App\Models\User;
use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Bus\Dispatchable;
use Illuminate\Queue\InteractsWithQueue;
use Illuminate\Queue\SerializesModels;

class SendWelcomeEmail implements ShouldQueue
{
    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;

    public function __construct(public User $user) {}

    public function handle(): void
    {
        // Buraya projedeki e-posta gönderme işlemini ekleyin.
    }
}

queue:work ile queue:listen farkı

queue:work uygulamayı bir kez belleğe yükler ve sürekli çalışır; bu nedenle kod değişikliklerini otomatik almaz, her deploy sonrası yeniden başlatılması gerekir. queue:listen ise her işte uygulamayı yeniden başlattığı için geliştirme ortamında kod değişikliklerini otomatik yakalar ama üretimde performans kaybına yol açar. Üretimde queue:work tercih edilmelidir.

Üretim ortamı için kontrol listesi

• Worker sürecini Supervisor gibi bir process manager ile yönetin; sunucu yeniden başladığında veya worker çöktüğünde otomatik ayağa kalksın.
• Başarısız işler için failed_jobs tablosunu (veya queue:failed komutunu) düzenli kontrol edin.
• queue:restart mevcut işi bitiren worker’ın çıkmasını ister; onu yeniden başlatan süreç yöneticisidir. Sinyal cache üzerinden saklanır, doğru cache bağlantısını kontrol edin.
• Kritik işler için --tries ve --backoff parametreleriyle yeniden deneme stratejisi belirleyin.
• --timeout, retry_after değerinden birkaç saniye kısa olmalıdır; aksi hâlde aynı iş iki kez çalışabilir. SQS’de karşılık visibility timeout’tur. İş zaman aşımı için PCNTL gerekir; dış HTTP çağrısında ayrıca bağlantı/yanıt zaman aşımı ayarlayın.

Paylaşımlı hosting ortamında worker çalıştırma

Sağlayıcınız kalıcı worker’a izin vermiyorsa cron ile queue:work --stop-when-empty değerlendirilebilir. Her dakika körlemesine başlatmayın: önceki çalışmanın bitmediği durumda çakışmayı önleyen kilit, çalışma süresi sınırı, doğru PHP yolu ve log kaydı gereklidir. Sürekli dolu kuyrukta bu komutun kısa sürede biteceğini varsaymayın. Planınızın süreç/cron limitlerini sağlayıcıdan doğrulayın.

Sık Sorulan Sorular

Queue worker olmadan job'lar çalışır mı?

database, Redis ve SQS’ye gönderilen işleri işleyecek worker gerekir. sync işi aynı süreçte çalıştırır; arka plan garantisi vermez. Başka bağlantı türlerinde kendi sürümünüzün davranışını kontrol edin.

Kaç worker süreci çalıştırmalıyım?

İş yüküne bağlıdır; küçük projelerde 1 worker yeterli olabilir, yoğun kuyruklarda birden fazla worker paralel çalıştırılarak işlem hızı artırılabilir.

Worker çöktüğünde ne olur?

Supervisor gibi bir process manager kullanılmıyorsa worker durur ve kuyruk birikmeye başlar; bu yüzden üretimde process manager kullanımı önemlidir.

database ve redis driver arasında performans farkı var mı?

İşlem hacmini sadece sürücü adına göre seçmeyin. Kendi işinizin süresini, veritabanı yükünü, kuyruk beklemesini ve işletim maliyetini ölçün. Redis seçimi ayrı servis yönetimi de getirir.

Job içinde hata oluşursa ne olur?

Deneme sınırı job tanımı veya worker ayarından gelebilir. Başarısız iş kaydı kullanılan yapılandırmaya bağlıdır; kayıt devre dışı olabilir. Başarısız işi yeniden denemeden önce yan etkilerin tekrar oluşup oluşmayacağını inceleyin.

İlgili okuma: Laravel merkez rehberi.

Queue worker izleme ve hata ayıklama

Üretimde queue worker çalışırken yalnızca işlemin tamamlanmasını değil, kuyruğun bekleme süresini ve başarısız job sayısını da izleyin. php artisan queue:failed ile hatalı işleri inceleyin; geçici ağ hatalarında kontrollü yeniden deneme, kalıcı veri hatalarında ise manuel inceleme uygulayın. Aynı job tekrar çalışabileceği için işlemleri mümkün olduğunca idempotent tasarlayın.

Laravel sürümünüze göre yapılandırma ayrıntıları değişebilir. Laravel’in resmî Queue dokümantasyonunu ve uygulamanızın deploy notlarını birlikte kontrol edin. Sunucu ve hosting işlemleri için hosting rehberlerine de bakabilirsiniz.

Bu yazı, Laravel Rehberi başlıklı merkez rehberin bir parçası. Kurulumdan yayına almaya kadar adımların sırasını oradan takip edebilirsiniz.

Kaynaklar ve İleri Okuma

• Laravel 13.x: Queues, zaman aşımı ve worker yeniden başlatma

İlgili Yazılar

• Laravel .env yapılandırması
• Laravel 13 proje kurulumu