Task Scheduling Laravel: Menjadwalkan Satu Tugas Artisan dengan Aman

Ada tugas aplikasi yang tidak perlu menunggu request pengguna: membuat laporan harian, mengirim pengingat, atau menjalankan perintah Artisan secara berkala. Tantangannya bukan sekadar menulis daily(). Anda perlu menempatkan definisi jadwal di source control, memilih frekuensi dan timezone yang masuk akal, lalu memeriksa apakah Laravel mengenali jadwal tersebut.

Laravel 13.x menyediakan scheduler untuk mendefinisikan pekerjaan berulang di dalam aplikasi. Untuk satu alur sederhana, gunakan satu perintah Artisan yang sudah ada, jadwalkan frekuensinya, kemudian baca hasil definisinya dengan php artisan schedule:list. Contoh di artikel ini mengikuti dokumentasi resmi dan belum dijalankan pada proyek Laravel. Karena itu, daftar jadwal hanya menunjukkan konfigurasi yang dikenali aplikasi; daftar tersebut bukan bukti bahwa tugas sudah berhasil dieksekusi.

Scheduler Laravel bekerja di level aplikasi

Scheduler adalah lapisan aplikasi untuk menyatakan kapan sebuah perintah atau pekerjaan boleh dipicu. Dokumentasi Laravel menempatkan definisi jadwal biasanya di routes/console.php. Alternatifnya, jadwal dapat didefinisikan melalui withSchedule di bootstrap/app.php jika file tersebut ingin dipakai khusus untuk definisi command.

Fokus artikel ini adalah satu perintah Artisan yang sudah tersedia, misalnya reports:daily. Nama itu hanya contoh; ganti dengan command yang benar-benar ada di aplikasi Anda. Laravel mendokumentasikan bahwa scheduler biasanya dipanggil melalui satu entri cron schedule:run di server, tetapi detail pemasangan cron, SSH, Supervisor, worker, dan deployment berada di luar cakupan artikel ini.

Definisikan satu tugas di source control

Contoh berikut mendefinisikan command reports:daily agar dipertimbangkan setiap hari pada pukul 01.00 menurut timezone yang ditentukan:

<?php

use Illuminate\Support\Facades\Schedule;

Schedule::command('reports:daily')
    ->dailyAt('01:00')
    ->timezone('Asia/Makassar');

Ada tiga keputusan yang terlihat jelas:

• Schedule::command('reports:daily') menunjuk ke Artisan command yang akan dijalankan.
• dailyAt('01:00') memilih frekuensi harian dan waktu pemicu.
• timezone('Asia/Makassar') membuat waktu jadwal dibaca dalam timezone tersebut, bukan sekadar mengandalkan asumsi timezone mesin.

Timezone bukan hiasan pada konfigurasi. Jika tim membaca jadwal sebagai WITA tetapi proses penjadwalan atau konfigurasi aplikasi memakai timezone lain, waktu yang diharapkan dapat berbeda. Pilih timezone berdasarkan kebutuhan aplikasi, lalu verifikasi konfigurasi deployment dan runtime secara terpisah. Contoh ini tidak menguji konversi waktu maupun eksekusi pada server.

Jika reports:daily belum terdaftar sebagai Artisan command, scheduler tidak mengubahnya menjadi command yang valid. Pastikan nama command berasal dari aplikasi Anda sendiri dan cocokkan syntax dengan dokumentasi Laravel 13.x serta versi dependency proyek.

Periksa definisi dengan schedule:list

Setelah definisi ditulis, gunakan perintah berikut untuk melihat jadwal yang dikenali Laravel:

php artisan schedule:list

Perintah ini membantu menjawab pertanyaan konfigurasi yang praktis: apakah command muncul, frekuensinya terbaca, dan kapan jadwal berikutnya dihitung. Ini adalah pemeriksaan terhadap definisi scheduler, bukan uji keberhasilan command.

Ada beberapa hal yang sengaja tidak dapat disimpulkan dari output tersebut:

• command pasti sudah dipicu oleh mekanisme scheduler;
• command selesai tanpa error;
• data laporan berhasil dibuat atau dikirim;
• timezone server dan deployment telah disetel sesuai harapan;
• tidak ada proses lain yang berjalan bersamaan;
• output command sudah tersimpan atau terkirim.

Untuk membuktikan perilaku runtime, aplikasi tetap memerlukan pemeriksaan dan pengujian yang sesuai dengan lingkungan sebenarnya. Artikel ini hanya menyiapkan batas aplikasi dan inspeksi daftar jadwal; tidak ada command, cron, server, database, atau deployment yang dijalankan.

Pilih frekuensi sesuai pekerjaan

dailyAt('01:00') hanyalah satu pilihan. Scheduler Laravel mendokumentasikan berbagai opsi frekuensi, termasuk interval per menit, per jam, harian, mingguan, dan pola lain yang tersedia pada versi framework. Jangan memilih frekuensi hanya karena contoh terlihat singkat.

Tanyakan terlebih dahulu:

1. Seberapa sering data atau tindakan memang perlu diperbarui?
2. Apakah tugas dapat berjalan lebih dari satu interval?
3. Apa yang terjadi jika jadwal berikutnya tiba sementara proses sebelumnya belum selesai?
4. Apakah jam yang dipilih memiliki arti bisnis yang jelas di timezone aplikasi?

Jawaban ini menentukan apakah frekuensi dasar sudah cukup atau perlu batas tambahan. Scheduler tidak mengetahui toleransi domain Anda secara otomatis.

Cegah overlap bila proses dapat bertumpuk

Secara default, tugas terjadwal dapat berjalan meskipun instance sebelumnya masih berjalan. Jika dua proses bersamaan akan mengulang pekerjaan yang sama atau menghasilkan output yang saling bertabrakan, dokumentasi Laravel menyediakan withoutOverlapping():

use Illuminate\Support\Facades\Schedule;

Schedule::command('reports:daily')
    ->dailyAt('01:00')
    ->timezone('Asia/Makassar')
    ->withoutOverlapping(30);

Angka 30 pada contoh adalah batas kedaluwarsa lock dalam menit, bukan jaminan bahwa command selesai dalam 30 menit atau bahwa semua kegagalan sudah ditangani. Dokumentasi menyebut default lock withoutOverlapping kedaluwarsa setelah 24 jam dan menyediakan schedule:clear-cache untuk kondisi lock tersisa setelah masalah tak terduga. Nilai yang tepat perlu mengikuti durasi dan perilaku command yang sebenarnya.

withoutOverlapping juga bukan pengganti idempotensi, transaksi, atau desain proses yang benar. Ia adalah mekanisme pencegah overlap pada scheduler dengan asumsi dan batas yang perlu diverifikasi terhadap lingkungan aplikasi. Pembahasan umum tentang atomic lock atau lifecycle queue bukan bagian artikel ini.

Bedakan overlap lokal dan beberapa server

Jika aplikasi menjalankan scheduler pada beberapa server, satu definisi jadwal dapat dipertimbangkan oleh lebih dari satu server. Laravel mendokumentasikan onOneServer() untuk tugas yang seharusnya hanya berjalan pada satu server pada satu waktu:

Schedule::command('reports:daily')
    ->dailyAt('01:00')
    ->timezone('Asia/Makassar')
    ->onOneServer();

Contoh ini hanya menunjukkan pilihan konfigurasi. Penggunaan onOneServer memiliki prasyarat koordinasi yang harus diperiksa pada aplikasi dan cache store Anda. Ia tidak membuktikan bahwa deployment tertentu sudah memakai konfigurasi yang dibutuhkan, dan tidak menjadi tutorial infrastruktur.

Untuk artikel ini, pilih satu kebutuhan yang benar-benar ada:

• gunakan withoutOverlapping() ketika masalah utamanya adalah instance tugas yang bertumpuk;
• pertimbangkan onOneServer() ketika scheduler dipanggil pada beberapa server dan tugas harus dipilih oleh satu server;
• jangan menambahkan keduanya tanpa memahami mengapa masing-masing batas diperlukan.

Batasi dan arahkan output secara sadar

Command Artisan mungkin menghasilkan output. Laravel menyediakan metode scheduler seperti sendOutputTo, appendOutputTo, emailOutputTo, dan emailOutputOnFailure untuk command atau exec. Contoh berikut hanya menunjukkan arah output ke file:

Schedule::command('reports:daily')
    ->dailyAt('01:00')
    ->timezone('Asia/Makassar')
    ->sendOutputTo(storage_path('logs/reports-daily.log'));

Path, izin tulis, rotasi, privasi data, dan pengelolaan file harus diperiksa pada aplikasi nyata. Mengarahkan output ke file tidak sama dengan membangun monitoring atau menjamin bahwa file selalu tersedia. Jika output dapat memuat data sensitif, tentukan terlebih dahulu apakah data tersebut layak disimpan.

Gunakan satu pilihan output yang punya tujuan jelas. Menambahkan banyak tujuan sekaligus membuat batas tanggung jawab lebih sulit ditinjau, terutama ketika command menghasilkan data yang tidak perlu dikirim melalui email.

Alur pemeriksaan yang ringkas

Untuk satu tugas berulang, alurnya dapat dibuat sederhana:

1. Pastikan command Artisan sudah dimiliki aplikasi dan dapat dipanggil dengan nama yang benar.
2. Definisikan jadwal di source control, misalnya pada routes/console.php.
3. Pilih satu frekuensi dan timezone yang sesuai dengan kebutuhan aplikasi.
4. Tambahkan withoutOverlapping atau onOneServer hanya jika masalahnya memang memerlukannya.
5. Arahkan output secara sadar bila command membutuhkannya.
6. Jalankan php artisan schedule:list pada lingkungan yang sesuai untuk memeriksa definisi.
7. Pisahkan pemeriksaan daftar jadwal dari pembuktian bahwa command benar-benar berjalan dan menghasilkan keluaran yang benar.

Langkah keempat sampai ketujuh penting karena scheduler mengatur pemicu, bukan keseluruhan keberhasilan pekerjaan. Command, akses data, konfigurasi runtime, dan mekanisme pemanggilannya tetap memiliki batas masing-masing.

Kapan pendekatan ini cukup?

Gunakan scheduler Laravel ketika kebutuhan Anda adalah menyatakan pekerjaan aplikasi yang berulang dalam source control dan membuat waktunya mudah ditinjau. Mulailah dari satu command, satu frekuensi, satu timezone, dan satu kebijakan overlap yang dapat dijelaskan.

Jika kebutuhan Anda berubah menjadi operasi server, pengelolaan worker queue, monitoring, performance tuning, atau jaminan uptime, itu sudah menjadi pekerjaan lain. Jangan memakai schedule:list sebagai bukti pengganti pengujian runtime. Baca outputnya sebagai pemeriksaan definisi, lalu verifikasi eksekusi dan hasil pada proyek Anda sendiri sebelum menganggap jadwal siap digunakan.