Laravel Scheduler: Otomatisasi Rekap Laporan, Pengingat Pembayaran, dan Pekerjaan Terjadwal
Admin HijrahKreativa
Penulis
Source code aplikasi, template web, dan ebook. Unduh dari akun setelah bayar. Lihat produk
Admin HijrahKreativa
Penulis
Menjadwalkan semua pekerjaan rutin aplikasi dari kode dengan satu entri cron: rekap kas bulanan, pengingat iuran, rekonsiliasi pembayaran, dan pembersihan data. Termasuk zona waktu, mencegah jadwal tumpang tindih dan ganda di banyak server, command yang idempoten, pemantauan kegagalan, serta test.
Aplikasi RW punya banyak pekerjaan yang harus berjalan sendiri tanpa ada yang menekan tombol:
| Pekerjaan | Jadwal |
|---|---|
| Membuat tagihan iuran bulan baru | Tanggal 1, pukul 00:30 |
| Mengirim pengingat iuran yang belum dibayar | Tanggal 10 dan 20, pukul 09:00 |
| Rekonsiliasi pembayaran yang masih pending ke payment gateway | Setiap 15 menit |
| Rekap laporan kas bulanan untuk pengurus | Tanggal 1, pukul 06:00 |
| Membersihkan token kedaluwarsa, log lama, job gagal | Setiap hari, pukul 02:00 |
| Backup database | Setiap hari, pukul 01:00 |
Cara lama adalah menulis satu entri crontab per pekerjaan di server. Hasilnya: jadwal tidak tercatat di repository, sulit di-review, berbeda antar server, dan mudah terlupa saat pindah server.
Laravel Scheduler memindahkan semua jadwal ke kode (routes/console.php). Server cukup punya satu entri cron yang memanggil schedule:run setiap menit, dan Laravel memutuskan pekerjaan mana yang jatuh tempo.
Hasil akhir:
schedule:work di container),routes/console.php dengan zona waktu Asia/Jakarta,| Komponen | Versi |
|---|---|
| PHP | 8.3+ (disarankan 8.4) |
| Laravel | 13.x |
| Cache driver dengan atomic lock | Redis, database, atau memcached (untuk onOneServer dan withoutOverlapping) |
| Queue | Sudah dikonfigurasi (lihat artikel Queue) |
| Testing | Pest 4 |
Artikel ini memakai command dari artikel sebelumnya: pembayaran:rekonsiliasi (payment gateway) dan iuran:kirim-pengingat (notifikasi WhatsApp).
Di server, buka crontab pengguna yang menjalankan aplikasi (bukan root):
crontab -u deploy -e
* * * * * cd /var/www/rw/current && php artisan schedule:run >> /dev/null 2>&1
Hanya itu yang dibutuhkan di sisi server. Untuk lingkungan container atau pengembangan lokal, jalankan proses yang berjalan terus:
php artisan schedule:work
Di Docker, jalankan schedule:work sebagai service tersendiri (satu replika saja), terpisah dari container web dan worker.
Cron server biasanya berjalan dalam UTC. Jadwal "pukul 09:00" harus berarti 09:00 WIB, bukan 09:00 UTC (16:00 WIB).
// config/app.php
'timezone' => 'UTC', // simpan waktu di database dalam UTC
// config/app.php (tambahan) — zona waktu untuk jadwal
'schedule_timezone' => env('SCHEDULE_TIMEZONE', 'Asia/Jakarta'),
Laravel membaca app.schedule_timezone sebagai zona waktu default semua jadwal. Bila aplikasi sudah memakai 'timezone' => 'Asia/Jakarta', jadwal otomatis mengikuti dan langkah ini bisa dilewati. Yang penting: putuskan secara eksplisit, karena "jam 9 pagi" yang ternyata jam 4 sore adalah bug yang sering terjadi.
Indonesia tidak memakai daylight saving time, sehingga Asia/Jakarta aman dari masalah jadwal terlewat atau terulang saat pergantian jam.
Setiap pekerjaan terjadwal sebaiknya berupa Artisan command. Command bisa dijalankan manual saat diperlukan, mudah di-test, dan punya opsi.
php artisan make:command BuatTagihanIuran
// app/Console/Commands/BuatTagihanIuran.php
namespace App\Console\Commands;
use App\Models\{Iuran, Keluarga, JenisIuran};
use Illuminate\Console\Command;
use Illuminate\Support\Carbon;
class BuatTagihanIuran extends Command
{
protected $signature = 'iuran:buat-tagihan
{--periode= : Format YYYY-MM, default bulan berjalan}
{--dry-run : Tampilkan jumlah tanpa menyimpan}';
protected $description = 'Membuat tagihan iuran bulanan untuk setiap keluarga aktif';
public function handle(): int
{
$periode = $this->option('periode')
? Carbon::createFromFormat('Y-m', $this->option('periode'))->startOfMonth()
: now(config('app.schedule_timezone'))->startOfMonth();
$kodePeriode = $periode->format('Y-m');
$jenis = JenisIuran::where('aktif', true)->where('bulanan', true)->get();
$dibuat = 0;
Keluarga::where('status', 'aktif')->chunkById(200, function ($keluargas) use ($jenis, $kodePeriode, $periode, &$dibuat) {
foreach ($keluargas as $keluarga) {
foreach ($jenis as $j) {
if ($this->option('dry-run')) {
$dibuat++;
continue;
}
// Idempoten: unique (keluarga_id, jenis_iuran_id, periode) di database
$iuran = Iuran::firstOrCreate(
['keluarga_id' => $keluarga->id, 'jenis_iuran_id' => $j->id, 'periode' => $kodePeriode],
['nominal' => $j->nominal, 'jatuh_tempo' => $periode->copy()->day(15), 'status' => 'belum_bayar'],
);
$dibuat += $iuran->wasRecentlyCreated ? 1 : 0;
}
}
});
$this->info(($this->option('dry-run') ? '[dry-run] ' : '')."Tagihan {$kodePeriode}: {$dibuat} baru.");
return self::SUCCESS;
}
}
Pastikan constraint unik ada di database, karena firstOrCreate saja tidak menjamin aman dari race condition:
// migration
$table->unique(['keluarga_id', 'jenis_iuran_id', 'periode']);
Sifat yang membuat command terjadwal aman:
php artisan iuran:buat-tagihan --periode=2026-10.--dry-run untuk memeriksa dampak sebelum benar-benar dijalankan.chunkById agar memori tetap rendah walau datanya ribuan.SUCCESS atau FAILURE) yang dipakai scheduler untuk menentukan sukses atau gagal.// routes/console.php
use Illuminate\Support\Facades\Schedule;
use App\Jobs\BuatLaporanBulananRw;
// --- Tagihan & pengingat ---------------------------------------------------
Schedule::command('iuran:buat-tagihan')
->monthlyOn(1, '00:30')
->onOneServer()
->withoutOverlapping()
->appendOutputTo(storage_path('logs/scheduler.log'));
Schedule::command('iuran:kirim-pengingat')
->monthlyOn(10, '09:00')
->onOneServer()
->withoutOverlapping();
Schedule::command('iuran:kirim-pengingat')
->monthlyOn(20, '09:00')
->onOneServer()
->withoutOverlapping();
// --- Pembayaran -------------------------------------------------------------
Schedule::command('pembayaran:rekonsiliasi --lebih-lama-dari=15')
->everyFifteenMinutes()
->between('06:00', '23:00')
->onOneServer()
->withoutOverlapping(10) // kunci kedaluwarsa setelah 10 menit
->runInBackground();
// --- Laporan ----------------------------------------------------------------
Schedule::job(new BuatLaporanBulananRw, 'laporan')
->monthlyOn(1, '06:00')
->onOneServer();
// --- Pemeliharaan -----------------------------------------------------------
Schedule::command('backup:run --only-db')->dailyAt('01:00')->onOneServer();
Schedule::command('model:prune')->dailyAt('02:00')->onOneServer();
Schedule::command('sanctum:prune-expired --hours=24')->dailyAt('02:10')->onOneServer();
Schedule::command('queue:prune-failed --hours=720')->dailyAt('02:20')->onOneServer();
Schedule::command('queue:prune-batches --hours=48 --unfinished=72')->dailyAt('02:25')->onOneServer();
Schedule::command('activitylog:clean')->weeklyOn(0, '03:00')->onOneServer();
Lihat daftar jadwal dan kapan berikutnya berjalan:
php artisan schedule:list
Penjelasan opsi yang dipakai:
| Opsi | Fungsi |
|---|---|
onOneServer() |
Bila aplikasi berjalan di beberapa server dan semuanya punya cron, hanya satu yang menjalankan tugas. Butuh cache terpusat (Redis/database) yang sama untuk semua server. |
withoutOverlapping($menit) |
Bila eksekusi sebelumnya belum selesai, eksekusi baru dilewati. Kunci kedaluwarsa setelah N menit (default 24 jam) agar tidak macet selamanya bila proses mati. |
runInBackground() |
Tugas dijalankan sebagai proses terpisah sehingga tugas lain di menit yang sama tidak menunggu. Hanya untuk command dan exec. |
between('06:00', '23:00') |
Batasi jendela waktu, misalnya tidak menggempur API pada malam hari. |
Schedule::job(...) |
Langsung men-dispatch job ke antrean; cocok untuk pekerjaan berat karena scheduler tidak ikut menunggu. |
Untuk menyederhanakan opsi yang berulang, kelompokkan:
Schedule::onOneServer()->withoutOverlapping()->group(function () {
Schedule::command('model:prune')->dailyAt('02:00');
Schedule::command('sanctum:prune-expired --hours=24')->dailyAt('02:10');
});
schedule:run berjalan setiap menit. Bila satu tugas makan waktu 20 menit tanpa runInBackground(), tugas lain di menit yang sama menunggu, dan proses cron menumpuk.
Pola yang lebih sehat: command terjadwal hanya memecah pekerjaan dan men-dispatch job, lalu worker mengerjakannya.
// app/Console/Commands/KirimPengingatIuran.php (ringkas)
public function handle(): int
{
$jumlah = 0;
Keluarga::query()
->whereHas('iuran', fn ($q) => $q->where('status', 'belum_bayar')->where('jatuh_tempo', '<=', now()->addDays(5)))
->where('wa_opt_in', true)
->chunkById(200, function ($keluargas) use (&$jumlah) {
foreach ($keluargas as $keluarga) {
$keluarga->kepala?->notify(new PengingatIuran($keluarga)); // notifikasi ShouldQueue → antrean whatsapp
$jumlah++;
}
});
$this->info("Pengingat dijadwalkan: {$jumlah}");
return self::SUCCESS;
}
Notifikasi PengingatIuran sudah mengatur pembatasan laju dan jam tenang (lihat artikel WhatsApp), jadi command hanya perlu memilih penerima.
Agar pengingat tidak terkirim ganda bila command dijalankan dua kali pada hari yang sama, catat pengiriman per periode:
$kunci = "pengingat:{$keluarga->id}:".now()->format('Y-m-d');
if (! Cache::add($kunci, true, now()->endOfDay())) {
continue; // sudah dikirim hari ini
}
model:pruneData sementara (token reset, log webhook, pesan WhatsApp lama) sebaiknya dibersihkan otomatis. Tandai model dengan trait Prunable:
// app/Models/WebhookCall.php
use Illuminate\Database\Eloquent\{Builder, Prunable};
class WebhookCall extends Model
{
use Prunable;
public function prunable(): Builder
{
return static::where('status', 'diproses')->where('created_at', '<=', now()->subDays(90));
}
}
// app/Models/PesanWhatsApp.php
public function prunable(): Builder
{
return static::where('created_at', '<=', now()->subMonths(6));
}
model:prune di jadwal akan menemukan semua model Prunable dan menghapus barisnya secara bertahap. Coba dulu dampaknya:
php artisan model:prune --pretend
Gunakan MassPrunable untuk tabel besar (menghapus langsung lewat query tanpa memuat model; event model tidak terpicu).
Sesuaikan masa simpan dengan kebutuhan audit dan kebijakan privasi: catatan transaksi kas tidak boleh ikut dihapus, sedangkan isi pesan WhatsApp sebaiknya tidak disimpan lebih lama dari perlu.
Tugas terjadwal yang gagal diam-diam adalah masalah paling umum: tidak ada yang sadar pengingat iuran tidak terkirim selama tiga bulan.
1. Hook sukses dan gagal
use Illuminate\Support\Facades\Notification;
use App\Notifications\TugasTerjadwalGagal;
Schedule::command('iuran:buat-tagihan')
->monthlyOn(1, '00:30')
->onOneServer()
->withoutOverlapping()
->onSuccess(fn () => Log::info('jadwal.tagihan.sukses'))
->onFailure(function () {
Notification::route('mail', config('app.admin_email'))
->notify(new TugasTerjadwalGagal('iuran:buat-tagihan'));
});
onFailure terpicu bila command mengembalikan kode keluar bukan nol. Itulah alasan command harus mengembalikan self::FAILURE saat ada masalah, bukan hanya menulis pesan error.
2. Heartbeat (dead man's switch)
Hook onFailure tidak menolong bila cron sendiri mati: tidak ada yang berjalan, jadi tidak ada yang gagal. Gunakan layanan pemantau heartbeat (Healthchecks.io, Better Stack, Cronitor, Oh Dear, atau buatan sendiri) yang memberi peringatan bila tidak menerima ping dalam jangka waktu tertentu.
Schedule::command('pembayaran:rekonsiliasi --lebih-lama-dari=15')
->everyFifteenMinutes()
->onOneServer()
->withoutOverlapping(10)
->pingOnSuccess(config('services.heartbeat.rekonsiliasi'))
->pingOnFailure(config('services.heartbeat.rekonsiliasi').'/fail');
// Heartbeat umum: membuktikan scheduler hidup
Schedule::call(fn () => Http::timeout(5)->get(config('services.heartbeat.scheduler')))
->everyFiveMinutes()
->name('heartbeat-scheduler')
->onOneServer();
URL ping disimpan di .env, bukan di kode. pingOnSuccess/pingOnFailure memakai HTTP client Laravel.
3. Event scheduler untuk log terpusat
// app/Providers/AppServiceProvider.php
use Illuminate\Console\Events\{ScheduledTaskFailed, ScheduledTaskFinished};
Event::listen(function (ScheduledTaskFinished $event) {
Log::channel('scheduler')->info('jadwal.selesai', [
'tugas' => $event->task->description ?? $event->task->command,
'detik' => round($event->runtime, 2),
]);
});
Event::listen(function (ScheduledTaskFailed $event) {
Log::channel('scheduler')->error('jadwal.gagal', [
'tugas' => $event->task->description ?? $event->task->command,
'error' => $event->exception->getMessage(),
]);
});
php artisan schedule:list # daftar & waktu berikutnya
php artisan schedule:test # pilih satu tugas dan jalankan sekarang
php artisan schedule:interrupt # hentikan tugas yang sedang berjalan (dipakai saat deploy)
php artisan schedule:clear-cache # hapus kunci withoutOverlapping yang macet
Saat aplikasi dalam mode maintenance (php artisan down), tugas terjadwal tidak berjalan kecuali ditandai ->evenInMaintenanceMode(). Pakai opsi itu hanya untuk tugas yang memang harus tetap jalan, misalnya backup.
// tests/Feature/Console/BuatTagihanIuranTest.php
it('membuat tagihan untuk setiap keluarga aktif', function () {
Keluarga::factory()->count(3)->create(['status' => 'aktif']);
Keluarga::factory()->create(['status' => 'pindah']);
JenisIuran::factory()->create(['aktif' => true, 'bulanan' => true, 'nominal' => 50_000]);
$this->artisan('iuran:buat-tagihan', ['--periode' => '2026-10'])
->expectsOutputToContain('3 baru')
->assertSuccessful();
expect(Iuran::where('periode', '2026-10')->count())->toBe(3);
});
it('idempoten: dijalankan dua kali tidak membuat tagihan ganda', function () {
Keluarga::factory()->count(2)->create(['status' => 'aktif']);
JenisIuran::factory()->create(['aktif' => true, 'bulanan' => true]);
$this->artisan('iuran:buat-tagihan', ['--periode' => '2026-10'])->assertSuccessful();
$this->artisan('iuran:buat-tagihan', ['--periode' => '2026-10'])
->expectsOutputToContain('0 baru')
->assertSuccessful();
expect(Iuran::count())->toBe(2);
});
it('dry-run tidak menyimpan apa pun', function () {
Keluarga::factory()->create(['status' => 'aktif']);
JenisIuran::factory()->create(['aktif' => true, 'bulanan' => true]);
$this->artisan('iuran:buat-tagihan', ['--periode' => '2026-10', '--dry-run' => true])->assertSuccessful();
expect(Iuran::count())->toBe(0);
});
Test bahwa jadwal terdaftar dengan benar:
// tests/Feature/Console/JadwalTest.php
use Illuminate\Console\Scheduling\Schedule;
function tugasTerjadwal(string $perintah)
{
return collect(app(Schedule::class)->events())
->first(fn ($e) => str_contains($e->command ?? '', $perintah));
}
it('tagihan iuran dibuat tanggal 1 pukul 00:30 WIB di satu server', function () {
$tugas = tugasTerjadwal('iuran:buat-tagihan');
expect($tugas)->not->toBeNull()
->and($tugas->expression)->toBe('30 0 1 * *')
->and($tugas->onOneServer)->toBeTrue()
->and($tugas->withoutOverlapping)->toBeTrue()
->and((string) $tugas->timezone)->toBe('Asia/Jakarta');
});
it('rekonsiliasi berjalan setiap 15 menit', function () {
expect(tugasTerjadwal('pembayaran:rekonsiliasi')->expression)->toBe('*/15 * * * *');
});
Test jadwal ini menangkap perubahan yang tidak disengaja, misalnya seseorang mengganti monthlyOn(1, ...) menjadi daily().
| Error / Gejala | Penyebab | Solusi |
|---|---|---|
| Tidak ada tugas yang berjalan | Entri cron tidak ada, salah pengguna, atau salah path | crontab -u deploy -l; jalankan php artisan schedule:run manual dan lihat outputnya |
| Tugas berjalan di jam yang salah | Zona waktu jadwal UTC | Set app.schedule_timezone atau ->timezone('Asia/Jakarta') |
| Tugas berjalan dua kali (dua server) | Tidak memakai onOneServer() atau cache tidak terpusat |
onOneServer() dan cache Redis/database bersama |
| Tugas tidak pernah jalan lagi setelah server restart | Kunci withoutOverlapping macet |
php artisan schedule:clear-cache; beri durasi kunci withoutOverlapping(30) |
| Tugas lain tertunda di menit yang sama | Tugas panjang berjalan berurutan | runInBackground() atau dispatch job ke queue |
onFailure tidak pernah terpicu |
Command selalu mengembalikan 0 | Kembalikan self::FAILURE saat gagal |
| Tidak ada yang tahu cron mati | Tidak ada pemantau dari luar | Heartbeat dengan pingOnSuccess |
| Tagihan ganda | Command tidak idempoten | Constraint unik di database dan firstOrCreate |
Tugas tidak jalan saat php artisan down |
Perilaku default | ->evenInMaintenanceMode() untuk tugas yang perlu |
Error Permission denied di log |
Cron berjalan sebagai root, file milik pengguna lain | Jalankan cron sebagai pengguna aplikasi |
Keamanan
.env.Performa
chunkById untuk data besar.between() untuk menghindari jam sibuk atau jam istirahat penerima.Maintainability
routes/console.php, ter-review lewat pull request.--dry-run.onFailure untuk kegagalan, heartbeat untuk cron yang mati.| Komponen | Versi |
|---|---|
| Laravel | 13.x |
| PHP | 8.4 |
| Redis | 7.x |
| MySQL | 8.4 |
| Pest | 4.x |
| Tanggal | 19 Oktober 2026 |
Sebelumnya
Laravel Queue dan Job: Memproses Email, Laporan, dan Task Berat di Background
Berikutnya
Membangun Integrasi Antar-Modul Laravel dengan Event, Listener, Queue, dan API
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