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 bu kuyruğu sürekli dinleyip işleri sırayla işler.
Hangi sürücüler (driver) kullanılabilir?
| Driver | Kullanım Senaryosu |
|---|---|
| database | Küçük/orta projeler, ek servis kurmadan hızlı başlangıç |
| redis | Yüksek performans, gecikme hassasiyeti olan üretim ortamları |
| sqs | AWS altyapısında ölçeklenebilir, yönetilen kuyruk |
| sync | Yerel geliştirme/test — işler kuyruğa girmeden anında çalışır |
Temel kurulum adımları
.envdosyasındaQUEUE_CONNECTIONdeğerini seçtiğiniz sürücüye göre ayarlayın (ör.redis).- Bir job sınıfı oluşturun:
php artisan make:job SendWelcomeEmail - Job içindeki
handle()metoduna asıl iş mantığını yazın. - İşi kuyruğa göndermek için kod içinde
SendWelcomeEmail::dispatch($user);kullanın. - Worker'ı başlatın:
php artisan queue:work
<?php namespace App\Jobs; 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) {} public function handle(): void { // E-posta gönderme mantığı burada çalışır } } 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_jobstablosunu (veyaqueue:failedkomutunu) düzenli kontrol edin. - Her deploy sonrası
php artisan queue:restartçalıştırarak worker'ların güncel kodu almasını sağlayın. - Kritik işler için
--triesve--backoffparametreleriyle yeniden deneme stratejisi belirleyin. - Uzun süren işler için
--timeoutdeğerini gerçekçi ayarlayın; aksi halde worker takılı kalabilir.
Paylaşımlı hosting ortamında worker çalıştırma
Paylaşımlı hosting ortamlarında sürekli çalışan bir worker süreci başlatmak genellikle mümkün olmaz; bu durumda QUEUE_CONNECTION=database ile birlikte cron üzerinden dakikada bir php artisan queue:work --stop-when-empty komutunu tetiklemek pratik bir alternatiftir. VPS veya bulut sunucularda ise Supervisor ile kalıcı worker çalıştırmak daha sağlıklıdır.
Sık Sorulan Sorular
Queue worker olmadan job'lar çalışır mı?
Hayır (sync driver hariç); worker çalışmıyorsa kuyruğa eklenen işler işlenmeden bekler.
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ı?
Evet, redis genellikle daha düşük gecikme ve daha yüksek işlem hacmi sunar; database driver küçük/orta ölçekli projeler için yeterli olabilir.
Job içinde hata oluşursa ne olur?
Job, tanımlı deneme sayısı (--tries) kadar tekrar denenir; başarısız olursa failed_jobs tablosuna kaydedilir ve manuel olarak incelenip yeniden denenebilir.
İlgili okuma: WordPress REST API’de Özel Endpoint Nasıl Yazılır?
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.
