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

Blog / REST API, Integrasi & Automation / Laravel Scheduler: Otomatisasi...
REST API, Integrasi & Automation

Laravel Scheduler: Otomatisasi Rekap Laporan, Pengingat Pembayaran, dan Pekerjaan Terjadwal

AD

Admin HijrahKreativa

Penulis

19 Oct 2026
13 min read
27 views

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.

Overview

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:

  • satu entri cron (atau schedule:work di container),
  • jadwal di routes/console.php dengan zona waktu Asia/Jakarta,
  • command terjadwal yang idempoten dan aman dijalankan ulang,
  • perlindungan dari tumpang tindih dan eksekusi ganda di banyak server,
  • pemantauan: log, notifikasi kegagalan, dan heartbeat,
  • test untuk command dan daftar jadwal.

Prerequisites

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).

Step-by-step Tutorial

Langkah 1: Satu Entri Cron

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.

Langkah 2: Zona Waktu

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.

Langkah 3: Command yang Idempoten

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:

  • Idempoten. Menjalankannya dua kali untuk periode yang sama tidak membuat tagihan ganda. Ini penting karena jadwal bisa terulang (server dipindah, cron diedit, admin menjalankan manual).
  • Parameter periode. Bila server mati pada tanggal 1, admin cukup menjalankan 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.
  • Kode keluar (SUCCESS atau FAILURE) yang dipakai scheduler untuk menentukan sukses atau gagal.

Langkah 4: Definisikan Jadwal

// 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');
});

Langkah 5: Command Berat? Lempar ke Queue

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
}

Langkah 6: Pruning Data dengan model:prune

Data 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.

Langkah 7: Pemantauan

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(),
    ]);
});

Langkah 8: Menjalankan Manual dan Saat Maintenance

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.

Langkah 9: Test

// 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().

Troubleshooting

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

Best Practices

Keamanan

  • Jalankan cron sebagai pengguna aplikasi, bukan root.
  • Simpan URL heartbeat dan kredensial di .env.
  • Tugas yang menyentuh data pribadi (ekspor, pengiriman massal) tetap tercatat di log aktivitas.
  • Pruning menjaga data pribadi tidak disimpan lebih lama dari yang diperlukan.

Performa

  • Command terjadwal memecah pekerjaan, worker queue yang mengerjakan.
  • chunkById untuk data besar.
  • Sebar tugas pemeliharaan di menit yang berbeda (02:00, 02:10, 02:20), bukan semuanya pada 00:00.
  • between() untuk menghindari jam sibuk atau jam istirahat penerima.

Maintainability

  • Semua jadwal di routes/console.php, ter-review lewat pull request.
  • Setiap command idempoten, menerima parameter periode, dan punya --dry-run.
  • Test untuk command dan untuk ekspresi jadwal.
  • Pemantauan dua lapis: onFailure untuk kegagalan, heartbeat untuk cron yang mati.

Related Articles

Last Tested

Komponen Versi
Laravel 13.x
PHP 8.4
Redis 7.x
MySQL 8.4
Pest 4.x
Tanggal 19 Oktober 2026

Bagikan artikel:

Artikel lainnya