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

Blog / REST API, Integrasi & Automation / Laravel Queue dan Job: Mempros...
REST API, Integrasi & Automation

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

AD

Admin HijrahKreativa

Penulis

19 Oct 2026
13 min read
9 views

Memindahkan pekerjaan lambat dari request ke background dengan aman: memilih driver, menulis job yang idempoten, retry dan backoff, timeout, middleware job, job unik, chain dan batch dengan progres, antrean berprioritas, penanganan job gagal, menjalankan worker di production dengan Supervisor atau Horizon, serta test.

Overview

Beberapa pekerjaan di aplikasi RW terlalu lambat atau terlalu rawan untuk dikerjakan selama pengguna menunggu:

Pekerjaan Waktu Risiko bila dikerjakan di request
Mengirim email konfirmasi pembayaran 1–5 detik Halaman lambat; gagal bila SMTP bermasalah
Membuat laporan PDF kas tahunan 10–60 detik Timeout; memblokir worker PHP
Mengirim pengingat ke 300 keluarga Menit Mustahil dalam satu request
Membuat thumbnail foto kegiatan 1–3 detik per foto Unggah terasa lambat
Memproses webhook pembayaran < 1 detik, tetapi harus andal Penyedia mengulang bila respons lambat

Queue menyimpan pekerjaan sebagai job di antrean, lalu worker terpisah memprosesnya. Pengguna langsung mendapat respons, dan pekerjaan yang gagal bisa diulang otomatis.

Masalah yang sering muncul saat memakai queue:

  • job dijalankan dua kali dan mengirim email ganda,
  • worker memakai kode lama setelah deploy,
  • job gagal diam-diam dan tidak ada yang tahu,
  • satu laporan raksasa memblokir antrean sehingga email reset password tertunda,
  • job dikirim di dalam transaksi database yang kemudian dibatalkan.

Hasil akhir:

  • konfigurasi queue Redis dengan beberapa antrean berprioritas,
  • job laporan yang idempoten dengan retry, timeout, dan middleware,
  • batch pembuatan laporan per RT dengan progres,
  • penanganan job gagal dan pemberitahuan,
  • worker production dengan Supervisor (atau Horizon),
  • test dengan Queue::fake() dan Bus::fake().

Prerequisites

Komponen Versi
PHP 8.3+ (disarankan 8.4), ekstensi redis atau paket predis/predis
Laravel 13.x
Redis 7.x (disarankan) atau database sebagai driver awal
Supervisor 4.x (Linux)
Laravel Horizon 5.x (opsional, untuk Redis)
Testing Pest 4

Step-by-step Tutorial

Langkah 1: Pilih Driver

Driver Kelebihan Kekurangan Cocok untuk
sync Tanpa worker Bukan antrean sungguhan; dikerjakan saat itu juga Test, lokal
database Tanpa layanan tambahan Membebani database, lebih lambat Aplikasi kecil, awal proyek
redis Cepat, mendukung Horizon Perlu Redis Production pada umumnya
sqs Terkelola, skala besar Bergantung AWS, batas ukuran pesan Infrastruktur AWS
# .env production
QUEUE_CONNECTION=redis
REDIS_HOST=127.0.0.1
REDIS_PASSWORD=...
REDIS_QUEUE_RETRY_AFTER=330
// config/queue.php (koneksi redis)
'redis' => [
    'driver'       => 'redis',
    'connection'   => env('REDIS_QUEUE_CONNECTION', 'default'),
    'queue'        => env('REDIS_QUEUE', 'default'),
    'retry_after'  => (int) env('REDIS_QUEUE_RETRY_AFTER', 90),
    'block_for'    => 5,
    'after_commit' => true,                 // dispatch di dalam transaksi ditunda sampai commit
],

Dua pengaturan penting:

  • retry_after harus lebih besar dari timeout job terlama. Bila job laporan butuh 300 detik tetapi retry_after 90, Redis menganggap job hilang dan menyerahkannya ke worker lain, sehingga laporan dibuat dua kali.
  • after_commit: true membuat job yang di-dispatch di dalam DB::transaction() baru masuk antrean setelah transaksi berhasil. Tanpa ini, worker bisa memproses job sebelum data yang dibutuhkannya tersimpan, atau memproses data dari transaksi yang akhirnya dibatalkan.

Untuk driver database, buat tabelnya:

php artisan make:queue-table
php artisan migrate

Langkah 2: Antrean Berprioritas

Pisahkan pekerjaan berdasarkan urgensi agar laporan berat tidak menunda email penting:

Antrean Isi Prioritas
kritis Reset password, OTP, webhook pembayaran Tertinggi
default Email notifikasi, event umum Normal
whatsapp Pesan WhatsApp (dengan pembatasan laju) Normal, worker terpisah
laporan PDF, ekspor, impor Rendah

Worker membaca antrean dari kiri ke kanan:

php artisan queue:work redis --queue=kritis,default --tries=3
php artisan queue:work redis --queue=laporan --timeout=300 --memory=512

Langkah 3: Menulis Job yang Baik

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

use App\Models\{LaporanKas, RukunTetangga};
use App\Services\Laporan\PembuatLaporanKas;
use Illuminate\Bus\Batchable;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Queue\Queueable;
use Illuminate\Queue\Middleware\{ThrottlesExceptions, WithoutOverlapping};
use Illuminate\Support\Facades\Storage;

class BuatLaporanKasRt implements ShouldQueue
{
    use Batchable, Queueable;

    public int $tries = 3;
    public int $timeout = 300;                 // detik; harus < retry_after koneksi
    public array $backoff = [30, 120];
    public bool $failOnTimeout = true;
    public bool $deleteWhenMissingModels = true;   // RT dihapus sebelum job jalan → buang job

    public function __construct(
        public RukunTetangga $rt,
        public string $periode,                // "2026-09"
    ) {
        $this->onQueue('laporan');
    }

    public function middleware(): array
    {
        return [
            (new WithoutOverlapping("laporan-kas:{$this->rt->id}:{$this->periode}"))->expireAfter(600),
            (new ThrottlesExceptions(maxAttempts: 3, decaySeconds: 300))->backoff(5),
        ];
    }

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

        $path = "laporan/kas/{$this->periode}/rt-{$this->rt->nomor}.pdf";

        // Idempoten: bila laporan untuk RT & periode ini sudah final, jangan buat ulang
        $laporan = LaporanKas::firstOrNew(['rukun_tetangga_id' => $this->rt->id, 'periode' => $this->periode]);
        if ($laporan->exists && $laporan->status === 'selesai' && Storage::disk('private')->exists($path)) {
            return;
        }

        $pdf = $pembuat->pdf($this->rt, $this->periode);          // pekerjaan berat
        Storage::disk('private')->put($path, $pdf);

        $laporan->fill(['path' => $path, 'status' => 'selesai', 'dibuat_pada' => now()])->save();
    }

    public function failed(\Throwable $e): void
    {
        LaporanKas::updateOrCreate(
            ['rukun_tetangga_id' => $this->rt->id, 'periode' => $this->periode],
            ['status' => 'gagal', 'pesan_error' => mb_substr($e->getMessage(), 0, 500)],
        );
    }
}

Prinsip yang diterapkan:

  • Idempoten. Queue menjamin setidaknya sekali, bukan tepat sekali. Job bisa berjalan dua kali (worker mati di tengah jalan, timeout, retry). Rancang job agar menjalankannya dua kali tidak menimbulkan efek ganda.
  • Kirim ID/model, bukan data besar. Model yang diteruskan ke constructor diserialisasi sebagai ID (lewat SerializesModels di dalam Queueable) lalu dimuat ulang dari database saat job berjalan, sehingga data selalu segar dan payload kecil.
  • Batasan eksplisit: tries, timeout, backoff.
  • WithoutOverlapping mencegah laporan yang sama dibuat bersamaan oleh dua worker.
  • ThrottlesExceptions berhenti sejenak bila layanan yang dipakai job (misalnya penyedia PDF) terus error, alih-alih menghabiskan percobaan dengan cepat.
  • failed() mencatat kegagalan agar pengguna tahu, bukan diam-diam hilang.

Langkah 4: Dispatch

// Langsung
BuatLaporanKasRt::dispatch($rt, '2026-09');

// Ditunda
BuatLaporanKasRt::dispatch($rt, '2026-09')->delay(now()->addMinutes(10));

// Hanya setelah transaksi DB berhasil (bila koneksi tidak memakai after_commit global)
BuatLaporanKasRt::dispatch($rt, '2026-09')->afterCommit();

// Setelah respons dikirim ke browser, tanpa worker (untuk pekerjaan ringan saja)
dispatch(fn () => Cache::forget('dasbor:ringkasan'))->afterResponse();

Email cukup dikirim dengan antrean:

Mail::to($warga)->queue(new KonfirmasiPembayaran($pembayaran));

Atau buat Mailable selalu masuk antrean dengan mengimplementasikan ShouldQueue.

Langkah 5: Job Unik

Untuk pekerjaan yang tidak boleh antre lebih dari satu kali bersamaan (misalnya sinkronisasi data ke layanan luar yang dipicu setiap perubahan):

use Illuminate\Contracts\Queue\ShouldBeUnique;

class SinkronkanWargaKeSistemKelurahan implements ShouldQueue, ShouldBeUnique
{
    use Queueable;

    public int $uniqueFor = 600;               // kunci keunikan berlaku 10 menit

    public function __construct(public int $wargaId) {}

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

    public function handle(): void { /* ... */ }
}

Bila warga diubah lima kali dalam satu menit, hanya satu job sinkronisasi yang antre. Fitur ini membutuhkan cache driver yang mendukung atomic lock (Redis, database, memcached).

Langkah 6: Chain dan Batch

Chain: job berurutan, berhenti bila satu gagal.

use Illuminate\Support\Facades\Bus;

Bus::chain([
    new ImporDataWarga($fileId),
    new ValidasiDataImpor($fileId),
    new KirimRingkasanImpor($fileId, $adminId),
])->onQueue('laporan')->catch(function (\Throwable $e) use ($adminId) {
    User::find($adminId)?->notify(new ImporGagal($e->getMessage()));
})->dispatch();

Batch: banyak job paralel dengan progres dan callback. Contoh: laporan kas bulanan untuk semua RT.

php artisan make:queue-batches-table
php artisan migrate
// app/Services/Laporan/BuatLaporanBulanan.php
use Illuminate\Bus\Batch;
use Illuminate\Support\Facades\Bus;

public function handle(string $periode, User $peminta): Batch
{
    $jobs = RukunTetangga::orderBy('nomor')->get()
        ->map(fn ($rt) => new BuatLaporanKasRt($rt, $periode))
        ->all();

    return Bus::batch($jobs)
        ->name("Laporan kas {$periode}")
        ->onQueue('laporan')
        ->allowFailures()                           // satu RT gagal tidak membatalkan RT lain
        ->then(fn (Batch $batch) => GabungkanLaporanRw::dispatch($periode, $peminta->id)->onQueue('laporan'))
        ->catch(fn (Batch $batch, \Throwable $e) => logger()->warning('laporan.batch_ada_gagal', ['batch' => $batch->id]))
        ->finally(fn (Batch $batch) => $peminta->notify(new LaporanSelesai($batch->id, $periode)))
        ->dispatch();
}

Tampilkan progres di antarmuka:

// GET /laporan/batch/{id}
public function progres(string $id)
{
    $batch = Bus::findBatch($id) ?? abort(404);

    return response()->json([
        'nama'     => $batch->name,
        'total'    => $batch->totalJobs,
        'selesai'  => $batch->processedJobs(),
        'gagal'    => $batch->failedJobs,
        'persen'   => $batch->progress(),
        'beres'    => $batch->finished(),
    ]);
}

Callback then, catch, dan finally diserialisasi bersama batch; jangan memakai $this di dalamnya, dan teruskan nilai sederhana (ID) alih-alih objek besar.

Pastikan hanya pengguna yang meminta (atau admin) yang bisa melihat progres batch tersebut, misalnya dengan menyimpan batch_id di tabel milik pengguna.

Langkah 7: Job Gagal

Laravel menyimpan job yang gagal setelah semua percobaan di tabel failed_jobs (sudah ada di proyek baru).

php artisan queue:failed                         # daftar job gagal
php artisan queue:retry 5f1c...                  # ulang satu job
php artisan queue:retry --queue=laporan          # ulang semua dari antrean tertentu
php artisan queue:forget 5f1c...                 # hapus satu
php artisan queue:prune-failed --hours=720       # hapus yang lebih lama dari 30 hari

Beri tahu tim saat ada job gagal:

// app/Providers/AppServiceProvider.php
use Illuminate\Queue\Events\JobFailed;
use Illuminate\Support\Facades\{Event, Queue};

Queue::failing(function (JobFailed $event) {
    Log::channel('queue')->error('job.gagal', [
        'job'     => $event->job->resolveName(),
        'antrean' => $event->job->getQueue(),
        'error'   => $event->exception->getMessage(),
    ]);
    // atau Notification::route('mail', config('app.admin_email'))->notify(new JobGagal(...));
});

Jadwalkan pembersihan:

Schedule::command('queue:prune-failed --hours=720')->daily();
Schedule::command('queue:prune-batches --hours=48 --unfinished=72')->daily();

Langkah 8: Worker di Production dengan Supervisor

Worker adalah proses PHP yang berjalan terus. Gunakan Supervisor agar worker dijalankan ulang bila mati.

; /etc/supervisor/conf.d/rw-worker.conf
[program:rw-worker-utama]
process_name=%(program_name)s_%(process_num)02d
command=php /var/www/rw/current/artisan queue:work redis --queue=kritis,default --sleep=3 --tries=3 --max-time=3600 --max-jobs=1000
user=deploy
numprocs=2
autostart=true
autorestart=true
stopasgroup=true
killasgroup=true
stopwaitsecs=360
redirect_stderr=true
stdout_logfile=/var/www/rw/shared/storage/logs/worker-utama.log

[program:rw-worker-laporan]
process_name=%(program_name)s_%(process_num)02d
command=php /var/www/rw/current/artisan queue:work redis --queue=laporan --timeout=300 --memory=512 --max-time=3600
user=deploy
numprocs=1
autostart=true
autorestart=true
stopwaitsecs=330
redirect_stderr=true
stdout_logfile=/var/www/rw/shared/storage/logs/worker-laporan.log

[program:rw-worker-whatsapp]
process_name=%(program_name)s_%(process_num)02d
command=php /var/www/rw/current/artisan queue:work redis --queue=whatsapp --sleep=3 --tries=5 --max-time=3600
user=deploy
numprocs=1
autostart=true
autorestart=true
stopwaitsecs=60
redirect_stderr=true
stdout_logfile=/var/www/rw/shared/storage/logs/worker-whatsapp.log
sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl status

Catatan penting:

  • --max-time dan --max-jobs membuat worker berhenti secara berkala dan dijalankan ulang oleh Supervisor, mencegah kebocoran memori jangka panjang.
  • stopwaitsecs harus lebih lama dari job terlama, agar Supervisor menunggu job selesai saat menghentikan worker.
  • Setiap deploy wajib menjalankan php artisan queue:restart. Worker memuat kode sekali saat mulai; tanpa restart, worker terus menjalankan kode lama.

Langkah 9: Horizon untuk Redis

Laravel Horizon menyediakan dasbor (antrean, throughput, waktu proses, job gagal) dan mengatur worker lewat konfigurasi kode.

composer require laravel/horizon
php artisan horizon:install
// config/horizon.php (sebagian)
'environments' => [
    'production' => [
        'utama' => [
            'connection' => 'redis',
            'queue'      => ['kritis', 'default'],
            'balance'    => 'auto',
            'minProcesses' => 1,
            'maxProcesses' => 6,
            'tries'      => 3,
            'timeout'    => 60,
        ],
        'laporan' => [
            'connection' => 'redis',
            'queue'      => ['laporan'],
            'maxProcesses' => 2,
            'tries'      => 3,
            'timeout'    => 300,
            'memory'     => 512,
        ],
    ],
],

Lindungi dasbor Horizon di production:

// app/Providers/HorizonServiceProvider.php
protected function gate(): void
{
    Gate::define('viewHorizon', fn ($user = null) => $user?->hasRole('super-admin'));
}

Dengan Horizon, Supervisor cukup menjalankan satu program php artisan horizon, dan perintah deploy menjadi php artisan horizon:terminate.

Langkah 10: Test

// tests/Feature/Queue/LaporanTest.php
use Illuminate\Support\Facades\{Bus, Queue, Storage};

it('men-dispatch job laporan ke antrean laporan', function () {
    Queue::fake();
    $admin = User::factory()->create()->assignRole('admin');
    $rt = RukunTetangga::factory()->create();

    $this->actingAs($admin)->post('/laporan/kas', ['rt_id' => $rt->id, 'periode' => '2026-09'])->assertRedirect();

    Queue::assertPushedOn('laporan', BuatLaporanKasRt::class, fn ($job) => $job->rt->is($rt) && $job->periode === '2026-09');
});

it('membuat batch untuk semua RT', function () {
    Bus::fake();
    RukunTetangga::factory()->count(5)->create();

    app(BuatLaporanBulanan::class)->handle('2026-09', User::factory()->create());

    Bus::assertBatched(fn ($batch) => $batch->name === 'Laporan kas 2026-09' && $batch->jobs->count() === 5);
});

it('job idempoten: menjalankan dua kali tidak membuat ulang laporan', function () {
    Storage::fake('private');
    $rt = RukunTetangga::factory()->create();
    $pembuat = Mockery::mock(PembuatLaporanKas::class);
    $pembuat->shouldReceive('pdf')->once()->andReturn('%PDF-1.7 ...');
    $this->app->instance(PembuatLaporanKas::class, $pembuat);

    (new BuatLaporanKasRt($rt, '2026-09'))->handle($pembuat);
    (new BuatLaporanKasRt($rt, '2026-09'))->handle($pembuat);   // kali kedua dilewati

    expect(LaporanKas::count())->toBe(1);
});

it('mencatat kegagalan saat job gagal', function () {
    $rt = RukunTetangga::factory()->create();

    (new BuatLaporanKasRt($rt, '2026-09'))->failed(new RuntimeException('PDF engine error'));

    expect(LaporanKas::first())->status->toBe('gagal');
});

Untuk test yang menjalankan job sungguhan, set QUEUE_CONNECTION=sync di phpunit.xml. Gunakan Queue::fake() / Bus::fake() bila hanya ingin memastikan job dikirim dengan benar.

Troubleshooting

Error / Gejala Penyebab Solusi
Job tidak pernah diproses Worker tidak berjalan atau membaca antrean lain supervisorctl status; samakan nama antrean di --queue
Perubahan kode tidak berlaku di job Worker masih memuat kode lama php artisan queue:restart (atau horizon:terminate) di setiap deploy
Job berjalan dua kali retry_after lebih pendek dari durasi job retry_after > timeout job terlama
MaxAttemptsExceededException Job habis percobaan atau timeout Naikkan timeout/tries seperlunya; periksa job lambat
ModelNotFoundException saat job berjalan Model dihapus setelah dispatch $deleteWhenMissingModels = true
Job memproses data yang belum tersimpan Dispatch di dalam transaksi sebelum commit after_commit di koneksi atau ->afterCommit()
Email reset password tertunda lama Antre di belakang laporan berat Pisahkan antrean dan prioritas
Memori worker terus naik Kebocoran memori jangka panjang --max-jobs, --max-time, --memory
ShouldBeUnique tidak berpengaruh Cache driver tidak mendukung lock Gunakan Redis/database untuk cache
Callback batch error saat dijalankan Closure memakai $this atau objek tak terserialisasi Gunakan nilai sederhana dan use variabel lokal

Best Practices

Keamanan

  • Jangan menaruh secret atau data pribadi berlebihan di payload job; kirim ID dan muat ulang data.
  • Lindungi dasbor Horizon dengan gate di production.
  • Otorisasi tetap dilakukan sebelum dispatch; job berjalan tanpa konteks pengguna yang login.
  • Log job gagal tanpa mencatat data sensitif.

Performa

  • Antrean terpisah per jenis pekerjaan dan prioritas.
  • Timeout yang realistis dan retry_after yang lebih besar.
  • Batch untuk pekerjaan yang bisa dipecah; chain untuk langkah yang berurutan.
  • Worker didaur ulang secara berkala (--max-jobs, --max-time).

Maintainability

  • Setiap job idempoten, dengan tries, backoff, timeout, dan failed() yang eksplisit.
  • Middleware job untuk pola umum (tanpa tumpang tindih, pembatasan laju, throttle error).
  • queue:restart sebagai bagian wajib skrip deploy.
  • Pemantauan job gagal dan pembersihan terjadwal.

Related Articles

Last Tested

Komponen Versi
Laravel 13.x
PHP 8.4
Redis 7.x
Laravel Horizon 5.x
Supervisor 4.2
Pest 4.x
Tanggal 19 Oktober 2026

Bagikan artikel:

Artikel lainnya