Laravel Queue dan Job: Memproses Email, Laporan, dan Task Berat di Background
Admin HijrahKreativa
Penulis
Source code aplikasi, template web, dan ebook. Unduh dari akun setelah bayar. Lihat produk
Admin HijrahKreativa
Penulis
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.
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:
Hasil akhir:
Queue::fake() dan Bus::fake().| 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 |
| 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
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
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:
SerializesModels di dalam Queueable) lalu dimuat ulang dari database saat job berjalan, sehingga data selalu segar dan payload kecil.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.// 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.
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).
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.
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();
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.php artisan queue:restart. Worker memuat kode sekali saat mulai; tanpa restart, worker terus menjalankan kode lama.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.
// 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.
| 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 |
Keamanan
Performa
retry_after yang lebih besar.--max-jobs, --max-time).Maintainability
tries, backoff, timeout, dan failed() yang eksplisit.queue:restart sebagai bagian wajib skrip deploy.| 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 |
Sebelumnya
Cara Mengirim Notifikasi WhatsApp dari Laravel melalui Provider API
Berikutnya
Laravel Scheduler: Otomatisasi Rekap Laporan, Pengingat Pembayaran, dan Pekerjaan Terjadwal
Dokumen ini menjelaskan prosedur konfigurasi autentikasi SSH Key antara server Ubuntu dan GitHub untuk memungkinkan server melakukan operasi Git, seperti clone, pull, dan fetch tanpa menggunakan username dan password akun GitHub.
Peta jalan arsitektur dari satu server hingga banyak server: tahapan pertumbuhan dan sinyal kapan naik tahap, prinsip yang sebaiknya diterapkan sejak awal (stateless, asinkron, data ber-tenant), read replica, pengelolaan data yang terus tumbuh, degradasi yang anggun saat layanan bermasalah, feature...
Menyiapkan lingkungan uji yang jujur, mengukur satu endpoint dengan ApacheBench, mensimulasikan perilaku pengguna sungguhan dengan k6 (skenario, threshold, autentikasi token), menelusuri penyebab request lambat dengan Telescope, memantau server selama pengujian, serta menulis laporan hasil dan angga...
Bagaimana Octane membuat Laravel lebih cepat dengan mem-boot aplikasi sekali dan menyimpannya di memori, apa yang sebenarnya dipercepat (dan yang tidak), risiko kebocoran state antar-request yang wajib dipahami, cara memeriksa kode agar aman untuk Octane, pemasangan dengan FrankenPHP di production,...
03 Nov 2026
19 Oct 2026
19 Oct 2026
19 Oct 2026
19 Oct 2026
19 Oct 2026
19 Oct 2026
19 Oct 2026
19 Oct 2026
19 Oct 2026
HijrahKreativa
Kami balas secepatnya
Masuk dulu untuk chat dengan tim kami. Riwayat chat Anda tersimpan di akun.
Masuk