Source code aplikasi, template web, dan ebook. Unduh dari akun setelah bayar. Lihat produk

Blog / Backend / Laravel Queue dan Job: Mempros...
Backend

Laravel Queue dan Job: Memproses Email, Laporan, dan Task Berat di Background

AD

Admin HijrahKreativa

Penulis

19 Oct 2026
11 min read
9 views

Memindahkan pekerjaan lambat dari siklus request ke antrean: konfigurasi, membuat job, retry dan failed job, batch, sampai menjalankan worker di production.

Pendahuluan

Bayangkan pelanggan menekan tombol Checkout. Di belakang layar aplikasi harus menyimpan pesanan, mengirim email konfirmasi, membuat invoice PDF, memberi tahu admin, dan memperbarui stok. Jika semuanya dikerjakan sebelum halaman merespons, pelanggan menunggu beberapa detik, dan jika layanan email sedang lambat, checkout ikut gagal.

Queue memecahkan ini: pekerjaan berat dimasukkan ke antrean dan dikerjakan oleh proses terpisah (worker), sementara pengguna langsung menerima respons.

Tanpa queue:
Request ─► simpan ─► kirim email ─► buat PDF ─► respons   (3-8 detik)

Dengan queue:
Request ─► simpan ─► masukkan job ─► respons              (< 300 ms)
                          │
                          └─► Worker: kirim email, buat PDF (di belakang layar)

Yang cocok dikirim ke queue: email dan notifikasi, pembuatan laporan atau ekspor, pemrosesan gambar, panggilan API eksternal, impor data besar, dan webhook keluar.

1. Memilih Driver Queue

Driver Kelebihan Kekurangan Cocok untuk
sync Tanpa setup Berjalan langsung, bukan background Development/testing
database Mudah, tanpa layanan tambahan Lebih lambat saat volume tinggi Aplikasi kecil-menengah
redis Cepat, fitur lengkap Perlu Redis Produksi dengan volume lebih besar
sqs / beanstalkd Terkelola / khusus Biaya atau setup tambahan Skala besar

Untuk memulai, database sudah cukup. Pindah ke redis saat volume naik.

Konfigurasi driver database

Laravel 11+ sudah menyertakan migrasi tabel jobs. Jika belum ada:

php artisan make:queue-table
php artisan make:queue-failed-table   # atau queue:failed-table pada versi lama
php artisan migrate
# .env
QUEUE_CONNECTION=database

Konfigurasi driver Redis

sudo apt install -y redis-server php8.3-redis
# .env
QUEUE_CONNECTION=redis
REDIS_CLIENT=phpredis
REDIS_HOST=127.0.0.1
REDIS_PASSWORD=null
REDIS_PORT=6379

2. Membuat Job Pertama

php artisan make:job KirimKonfirmasiPesanan
// app/Jobs/KirimKonfirmasiPesanan.php
namespace App\Jobs;

use App\Mail\KonfirmasiPesananMail;
use App\Models\Order;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Queue\Queueable;
use Illuminate\Support\Facades\Mail;

class KirimKonfirmasiPesanan implements ShouldQueue
{
    use Queueable;

    public int $tries = 3;
    public int $timeout = 60;

    public function __construct(public Order $order) {}

    public function backoff(): array
    {
        return [10, 60, 300];   // jeda antar percobaan: 10 detik, 1 menit, 5 menit
    }

    public function handle(): void
    {
        Mail::to($this->order->email)->send(new KonfirmasiPesananMail($this->order));
    }
}

Pada versi Laravel yang lebih lama, trait Queueable ditulis lengkap dengan Dispatchable, InteractsWithQueue, SerializesModels. Pada Laravel 11+, trait Queueable dari Illuminate\Foundation\Queue sudah mencakupnya.

Model yang dikirim lewat constructor diserialisasi sebagai ID, lalu diambil ulang dari database saat job dijalankan. Jadi data yang diproses adalah data terbaru, bukan salinan lama.

Mengirim job ke antrean

use App\Jobs\KirimKonfirmasiPesanan;

public function store(CheckoutRequest $request)
{
    $order = Order::create($request->validated());

    KirimKonfirmasiPesanan::dispatch($order);

    return redirect()->route('orders.show', $order);
}

Opsi pengiriman yang sering dipakai:

KirimKonfirmasiPesanan::dispatch($order)->delay(now()->addMinutes(5));  // tunda
KirimKonfirmasiPesanan::dispatch($order)->onQueue('emails');            // antrean khusus
KirimKonfirmasiPesanan::dispatch($order)->onConnection('redis');        // koneksi khusus
KirimKonfirmasiPesanan::dispatchAfterResponse($order);                  // setelah respons dikirim
KirimKonfirmasiPesanan::dispatchSync($order);                           // langsung (untuk debugging)

Pastikan job dikirim setelah transaksi database selesai

Jika job dikirim di dalam DB::transaction dan worker menjalankannya sebelum transaksi di-commit, data pesanan belum ada dan job gagal.

KirimKonfirmasiPesanan::dispatch($order)->afterCommit();

Atau atur global di config/queue.php:

'database' => [
    // ...
    'after_commit' => true,
],

3. Mengirim Email Lewat Queue

Cara paling ringkas adalah membuat Mailable yang langsung antre.

php artisan make:mail KonfirmasiPesananMail --markdown=emails.konfirmasi
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Mail\Mailable;

class KonfirmasiPesananMail extends Mailable implements ShouldQueue
{
    use Queueable, SerializesModels;

    public function __construct(public Order $order) {}
    // envelope() dan content() seperti biasa
}
Mail::to($order->email)->queue(new KonfirmasiPesananMail($order));
Mail::to($order->email)->later(now()->addMinutes(10), new KonfirmasiPesananMail($order));

4. Menjalankan Worker

php artisan queue:work
   INFO  Processing jobs from the [default] queue.

  2026-10-19 09:14:02 App\Jobs\KirimKonfirmasiPesanan ........ RUNNING
  2026-10-19 09:14:03 App\Jobs\KirimKonfirmasiPesanan ........ 812.44ms DONE
  2026-10-19 09:14:03 App\Jobs\BuatInvoicePdf ................ RUNNING
  2026-10-19 09:14:05 App\Jobs\BuatInvoicePdf ................ 1s DONE

Opsi yang berguna:

php artisan queue:work --queue=emails,default   # prioritas: emails dulu
php artisan queue:work --tries=3 --timeout=90
php artisan queue:work --max-time=3600          # berhenti tiap jam (akan di-restart supervisor)
php artisan queue:work --max-jobs=1000          # berhenti setelah 1000 job
php artisan queue:work --sleep=3                # jeda saat antrean kosong

Worker adalah proses yang berjalan lama. Ia memuat kode sekali lalu menyimpannya di memori. Setelah deploy, kode baru tidak terbaca sampai worker di-restart (php artisan queue:restart).

Mengapa memakai queue:work dan bukan queue:listen

queue:listen memuat ulang framework untuk setiap job, sehingga lebih lambat. queue:work jauh lebih efisien dan menjadi pilihan di production.

5. Menangani Kegagalan

Job bisa gagal: server email down, API timeout, atau bug. Laravel menyediakan retry otomatis dan tabel failed_jobs.

class KirimKonfirmasiPesanan implements ShouldQueue
{
    use Queueable;

    public int $tries = 3;
    public int $maxExceptions = 2;          // maksimal exception sebelum dianggap gagal
    public int $timeout = 60;

    public function failed(\Throwable $e): void
    {
        // dipanggil setelah semua percobaan habis
        logger()->error('Konfirmasi gagal dikirim', [
            'order_id' => $this->order->id,
            'error'    => $e->getMessage(),
        ]);
        // contoh: tandai di database atau beri tahu admin
    }
}

Mengelola job yang gagal:

php artisan queue:failed                 # daftar job gagal
php artisan queue:retry 5                # ulang job dengan ID 5
php artisan queue:retry all              # ulang semua
php artisan queue:forget 5               # hapus satu
php artisan queue:flush                  # hapus semua
+--------------------------------------+------------+---------+---------------------------------+
| ID                                   | Connection | Queue   | Failed At                       |
+--------------------------------------+------------+---------+---------------------------------+
| 9c3e2a4f-...                         | database   | default | 2026-10-19 09:20:11             |
+--------------------------------------+------------+---------+---------------------------------+

Idempotensi: job harus aman dijalankan ulang

Karena job bisa dicoba lebih dari sekali, rancang agar menjalankannya dua kali tidak menimbulkan efek ganda (misalnya email terkirim dua kali atau saldo terpotong dua kali).

public function handle(): void
{
    $order = $this->order->fresh();

    if ($order->confirmation_sent_at) {
        return;                              // sudah pernah, lewati
    }

    Mail::to($order->email)->send(new KonfirmasiPesananMail($order));

    $order->update(['confirmation_sent_at' => now()]);
}

Mencegah job ganda yang bersamaan

use Illuminate\Contracts\Queue\ShouldBeUnique;

class HitungUlangStok implements ShouldQueue, ShouldBeUnique
{
    public int $uniqueFor = 600;             // kunci selama 10 menit

    public function uniqueId(): string
    {
        return (string) $this->product->id;
    }
}

Atau memakai middleware untuk membatasi konkurensi dan laju:

use Illuminate\Queue\Middleware\{RateLimited, WithoutOverlapping};

public function middleware(): array
{
    return [
        new WithoutOverlapping($this->order->id),
        // new RateLimited('kirim-wa'),      // batasi laju panggilan API eksternal
    ];
}

6. Contoh Nyata: Laporan Berat di Background

Ekspor laporan penjualan setahun bisa memakan puluhan detik. Alih-alih membuat pengguna menunggu, jalankan sebagai job lalu beri tahu saat selesai.

php artisan make:job BuatLaporanPenjualan
class BuatLaporanPenjualan implements ShouldQueue
{
    use Queueable;

    public int $timeout = 600;
    public int $tries = 1;

    public function __construct(
        public int $userId,
        public string $dari,
        public string $sampai,
    ) {}

    public function handle(): void
    {
        $path = "laporan/penjualan-{$this->dari}-{$this->sampai}-".now()->timestamp.'.csv';
        $stream = fopen('php://temp', 'w+');

        fputcsv($stream, ['Tanggal', 'No Pesanan', 'Pelanggan', 'Total']);

        Order::query()
            ->whereBetween('created_at', [$this->dari, $this->sampai])
            ->with('customer:id,name')
            ->lazyById(1000)                 // hemat memori
            ->each(fn ($o) => fputcsv($stream, [
                $o->created_at->format('Y-m-d'),
                $o->number,
                $o->customer->name,
                $o->total,
            ]));

        rewind($stream);
        Storage::disk('local')->put($path, stream_get_contents($stream));
        fclose($stream);

        User::find($this->userId)->notify(new LaporanSiap($path));
    }
}
// Controller
BuatLaporanPenjualan::dispatch(auth()->id(), $request->dari, $request->sampai);

return back()->with('success', 'Laporan sedang dibuat. Anda akan diberi tahu saat siap.');

Gunakan lazyById() atau chunkById() untuk data besar agar memori tidak habis, dan simpan file di storage privat, bukan folder publik. Berikan tautan unduh yang dilindungi autentikasi.

7. Rantai dan Batch

Job berantai (berurutan)

Job berikutnya hanya berjalan jika sebelumnya sukses.

use Illuminate\Support\Facades\Bus;

Bus::chain([
    new ProsesPembayaran($order),
    new KurangiStok($order),
    new BuatInvoicePdf($order),
    new KirimKonfirmasiPesanan($order),
])->dispatch();

Batch (paralel dengan pelacakan progres)

Cocok untuk impor atau pengiriman massal. Butuh tabel job_batches:

php artisan make:queue-batches-table
php artisan migrate
use Illuminate\Bus\Batch;
use Illuminate\Support\Facades\Bus;

$jobs = $pelanggan->map(fn ($p) => new KirimPromo($p));

$batch = Bus::batch($jobs)
    ->name('Promo Akhir Tahun')
    ->allowFailures()
    ->then(fn (Batch $b) => logger()->info('Semua terkirim'))
    ->catch(fn (Batch $b, \Throwable $e) => logger()->error($e->getMessage()))
    ->finally(fn (Batch $b) => logger()->info("Selesai: {$b->processedJobs()} job"))
    ->dispatch();

$batch->id;   // simpan untuk menampilkan progres

Di dalam job batch, tambahkan trait Batchable dan periksa pembatalan:

use Illuminate\Bus\Batchable;

public function handle(): void
{
    if ($this->batch()?->cancelled()) {
        return;
    }
    // proses
}

8. Worker di Production dengan Supervisor

Di localhost, worker dijalankan manual. Di server, worker harus hidup terus dan otomatis bangkit bila mati. Gunakan Supervisor.

sudo apt install -y supervisor
sudo nano /etc/supervisor/conf.d/laravel-worker.conf
[program:laravel-worker]
process_name=%(program_name)s_%(process_num)02d
command=php /var/www/laravel-app/artisan queue:work --queue=emails,default --sleep=3 --tries=3 --max-time=3600
autostart=true
autorestart=true
stopasgroup=true
killasgroup=true
user=www-data
numprocs=3
redirect_stderr=true
stdout_logfile=/var/www/laravel-app/storage/logs/worker.log
stopwaitsecs=3610
sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl status
laravel-worker:laravel-worker_00   RUNNING   pid 21401, uptime 0:02:11
laravel-worker:laravel-worker_01   RUNNING   pid 21402, uptime 0:02:11
laravel-worker:laravel-worker_02   RUNNING   pid 21403, uptime 0:02:11

Catatan penting:

  • stopwaitsecs harus lebih besar dari durasi job terlama agar saat restart, job yang sedang berjalan tidak terputus.
  • numprocs menentukan berapa job diproses paralel. Sesuaikan dengan CPU dan RAM.
  • Setiap worker memakai memori sendiri, jadi perhitungkan saat menentukan jumlahnya.

Saat deploy

php artisan queue:restart

Perintah ini memberi sinyal agar worker berhenti dengan anggun setelah menyelesaikan job saat ini, lalu Supervisor menyalakannya kembali dengan kode baru.

9. Memantau Queue

Pemantauan sederhana lewat Artisan:

php artisan queue:monitor redis:default,redis:emails --max=100
php artisan queue:failed

Untuk tampilan lengkap pada Redis, pakai Laravel Horizon: dashboard web berisi throughput, waktu tunggu, job gagal, dan penyeimbangan worker otomatis.

composer require laravel/horizon
php artisan horizon:install
php artisan migrate
php artisan horizon

Batasi akses dashboard Horizon (Horizon::auth()) hanya untuk admin, karena ia memperlihatkan data job.

10. Menguji Job

Gunakan Queue::fake() agar test tidak benar-benar menjalankan job.

use Illuminate\Support\Facades\Queue;

public function test_checkout_mengirim_konfirmasi_ke_queue(): void
{
    Queue::fake();

    $this->actingAs(User::factory()->create())
        ->post('/checkout', $this->dataValid())
        ->assertRedirect();

    Queue::assertPushed(KirimKonfirmasiPesanan::class, 1);
}

Untuk menguji isi handle() itu sendiri, panggil job secara langsung:

(new KirimKonfirmasiPesanan($order))->handle();

11. Kesalahan yang Sering Terjadi

Masalah Penyebab Solusi
Job tidak jalan sama sekali Worker belum berjalan, atau QUEUE_CONNECTION=sync Jalankan queue:work, cek .env
Kode baru tidak terbaca Worker masih memakai kode lama php artisan queue:restart setelah deploy
ModelNotFoundException di job Data dihapus sebelum job jalan, atau dikirim sebelum commit afterCommit(), tangani model yang hilang
Email terkirim dua kali Job di-retry tanpa idempotensi Tandai di database, atau pakai unique job
Worker memakan memori terus Kebocoran pada proses panjang --max-time atau --max-jobs agar restart berkala
Job menggantung lalu diulang timeout lebih besar dari retry_after Pastikan retry_after > timeout di config/queue.php
Job gagal tanpa jejak Tidak ada pencatatan Implementasikan failed() dan pantau failed_jobs

Aturan penting soal konfigurasi: nilai retry_after di config/queue.php harus lebih besar daripada timeout job terpanjang. Jika tidak, job yang masih berjalan dianggap macet dan dijalankan lagi oleh worker lain.

Checklist

  • ☐ QUEUE_CONNECTION bukan sync di production.
  • ☐ Tabel jobs dan failed_jobs sudah ada (atau Redis terpasang).
  • ☐ Worker berjalan di bawah Supervisor dan otomatis hidup kembali.
  • ☐ php artisan queue:restart ada di skrip deploy.
  • ☐ Job diberi tries, timeout, dan backoff yang masuk akal.
  • ☐ Job bersifat idempotent, aman dijalankan ulang.
  • ☐ afterCommit() dipakai untuk job yang dikirim dari dalam transaksi.
  • ☐ retry_after lebih besar dari timeout job terlama.
  • ☐ Job gagal dipantau dan ada penanganan di failed().
  • ☐ Ada test dengan Queue::fake() untuk alur utama.

Penutup

Queue adalah salah satu peningkatan paling berdampak untuk aplikasi Laravel: respons halaman jadi cepat, tugas berat tidak lagi memblokir pengguna, dan kegagalan layanan eksternal tidak langsung merusak pengalaman mereka. Mulailah dengan memindahkan email dan notifikasi, lalu laporan dan pemrosesan berat. Pastikan worker dikelola Supervisor, job dirancang idempotent, dan kegagalan terpantau, maka antrean Anda akan menjadi tulang punggung yang dapat diandalkan.

Bagikan artikel:

Artikel lainnya