Laravel Doctor: Cek Kesehatan Aplikasi Laravel dengan Satu Perintah Artisan

Di Laracon US 2026 di Boston, Laravel memperkenalkan Laravel Doctor, package resmi yang menambahkan perintah php artisan doctor ke aplikasi Laravel. Tujuan utamanya sederhana: menjalankan serangkaian health check terhadap aplikasi Anda dan memberitahu apa yang salah — bahkan memperbaikinya secara otomatis jika memungkinkan.

Sebelumnya, saat aplikasi Laravel tiba-tiba tidak berjalan, developer harus memeriksa satu per satu: apakah file .env ada, apakah APP_KEY sudah digenerate, apakah direktori storage writable, apakah koneksi queue sudah benar di production, dan seterusnya. Laravel Doctor mengubah daftar mental tersebut menjadi kode yang bisa dijalankan berulang kali.

Bagaimana Laravel Doctor Bekerja

Setiap diagnostic di Laravel Doctor adalah satu class yang memeriksa satu hal dan mengembalikan salah satu dari enam status: pass, notice, warn, fail, skip, atau error. Secara default, perintah akan keluar dengan status non-zero jika ada fail atau error. Jika Anda ingin warning juga membuat build gagal, tambahkan opsi --fail-on=warn. Jika hanya ingin laporan tanpa mengubah exit code, gunakan --fail-on=never.

Laravel Doctor memahami environment: local, production, dan staging. Suatu masalah bisa dianggap fail di production, tapi hanya notice di local. Sebagai contoh, koneksi queue sync dianggap pass di local, tapi akan menghasilkan warning di production. Begitu pula dengan bootstrap cache: missing di production menjadi warning, tapi di local dianggap pass.

Diagnostic yang Sudah Disertakan

Secara default, Laravel Doctor memeriksa beberapa area penting berikut:

• Environment: keberadaan .env, APP_KEY, versi PHP sesuai composer.json, ekstensi yang dibutuhkan, dan timezone.
• Composer: dependencies sudah terinstal, autoload bisa di-optimize, serta masalah pada composer.lock yang bisa diperbaiki.
• Configuration: file config bisa load dan di-cache, nilai yang dibutuhkan driver sudah di-set, serta status bootstrap cache.
• Database: koneksi default bisa dijangkau, file SQLite ada jika digunakan, dan migrasi pending.
• Cache, Queue, Scheduler, dan Session: driver yang aktif bisa dijangkau, koneksi Redis dicek, serta task scheduler muncul sebagai notice.
• Storage: default disk bisa dijangkau, direktori yang dibutuhkan writable, dan symlink storage:link sudah ada.
• Security: debug mode sesuai environment, .env masuk .gitignore, dan dependency audit.

Instalasi dan Penggunaan Dasar

Instal Laravel Doctor sebagai dev dependency:

composer require laravel/doctor --dev

Jalankan diagnostic:

php artisan doctor

Jika ada masalah yang bisa diperbaiki otomatis, Laravel Doctor akan menampilkan konfirmasi sebelum melakukan perbaikan. Untuk melewati konfirmasi dan langsung memperbaiki, gunakan:

php artisan doctor --fix

Perintah --fix bisa membuat file .env yang hilang, generate APP_KEY, mematikan debug mode di production, menambahkan .env ke .gitignore, membuat public storage link, dan memperbaiki permission direktori storage.

Anda juga bisa memfilter diagnostic berdasarkan class, group, atau package:

php artisan doctor --only=security
php artisan doctor --except=laravel/*

Membuat Diagnostic Kustom

Package pihak ketiga maupun aplikasi Anda sendiri bisa mendaftarkan diagnostic melalui facade Doctor:

use Laravel\Doctor\Facades\Doctor;
use Vendor\Package\Diagnostics\HorizonIsRunning;

public function boot(): void
{
    Doctor::diagnostic(HorizonIsRunning::class);
}

Untuk membuat class diagnostic baru, gunakan perintah:

php artisan make:diagnostic HorizonIsRunning

Class tersebut akan disimpan di app/Doctor/Diagnostics, extends Laravel\Doctor\Diagnostic, dan mengimplementasikan method check() yang mengembalikan DiagnosticResult. Jika diagnostic bisa memperbaiki masalahnya sendiri, implementasikan contract Laravel\Doctor\Contracts\Fixable dan tandai hasil dengan ->fixable().

Output untuk CI dan AI Agent

Selain output CLI, Laravel Doctor mendukung format JSON untuk mesin:

php artisan doctor --format=json

Dan format GitHub Actions annotations:

php artisan doctor --format=github

Untuk coding agent seperti Claude Code atau Cursor, Laravel Doctor secara otomatis beralih ke format PAO (Prompt Agent Output): satu baris JSON dengan ringkasan dan daftar issue yang bisa ditindaklanjuti.

Contoh output PAO:

{"tool":"doctor","result":"failed","diagnostics":27,"failed":1,"warnings":1,"notices":0,"passed":19,"skipped":6,"issues":[{"name":".env file exists","status":"fail","summary":"The application does not have an environment file.","fix":"Run `cp .env.example .env`, then review the copied values.","fixable":true}]}

Kesimpulan

Laravel Doctor mengubah proses diagnostic manual menjadi bagian dari workflow yang bisa diotomatisasi. Cocok digunakan saat setup aplikasi baru, sebelum deploy, maupun sebagai final check oleh AI coding agent. Package ini mensyaratkan PHP 8.3 dan Laravel 12 atau 13, serta dirilis di bawah lisensi MIT. Dokumentasi lengkap dan kode sumber tersedia di repositori Laravel Doctor.

Jika aplikasi Laravel Anda sering mengalami masalah konfigurasi yang sulit dideteksi, Laravel Doctor bisa jadi alat wajib di toolchain Anda.