Laravel Doctor: khám sức khỏe app Laravel bằng một lệnh

Mỗi lần chuẩn bị release, danh sách "nhớ kiểm tra" trong đầu mỗi người một khác: người nhớ APP_DEBUG, người nhớ queue worker, người nhớ quyền ghi thư mục storage. Laravel Doctor — package first-party ra mắt tháng 7/2026 — gom đống đó lại thành một lệnh duy nhất.

Bài này tóm tắt nhanh: Laravel Doctor làm được gì, dùng ở đâu cho hợp lý, và nó không thay thế được gì.

Cài và chạy trong 30 giây

composer require laravel/doctor --dev

Cài với --dev vì đây là công cụ chẩn đoán lúc phát triển, không cần nằm trong dependency chạy thật ở production.

php artisan doctor

Mỗi diagnostic chạy đúng một phép kiểm tra và trả về một trạng thái: pass, notice, warn, fail, skip hoặc error. Một số lỗi có sẵn cách sửa an toàn và xác định — khi đó Doctor tự vá được.

Laravel Doctor kiểm tra những gì

Bộ diagnostic mặc định phủ các nhóm sau:

• Environment — file .env, APP_KEY, phiên bản PHP, extension, timezone.

• Composer — dependency, autoload, các vấn đề ở lock file.

• Configuration — nạp file config, config cache, bootstrap.

• Database — kết nối có tới được không, file SQLite, migration.

• Cache / queue / scheduler / session — driver có reachable không, các check liên quan Redis.

• Storage — disk, quyền ghi thư mục, symlink.

• Security — debug mode, .env đã nằm trong .gitignore chưa, audit dependency.

Đây đúng là những thứ hay quên nhất khi dựng lại môi trường hoặc lên server mới.

Vài cờ đáng nhớ

• --fix — áp dụng luôn các bản vá có sẵn, không hỏi lại.

• --only= / --except= — chạy hoặc bỏ qua diagnostic theo class, group hoặc package (phân cách bằng dấu phẩy).

• --bail — dừng ngay ở lỗi đầu tiên.

• --fail-on=warn — coi cảnh báo cũng là thất bại; --fail-on=never thì chỉ báo cáo, không bao giờ fail.

• --format=json|github|agent — xuất JSON, annotation cho GitHub Actions, hoặc JSON tối ưu cho AI agent.

Muốn cố định only/except cho cả team thì publish config: php artisan vendor:publish --tag=doctor-config.

Cắm vào CI/CD

Doctor trả exit code 0 khi mọi thứ ổn và khác 0 khi có fail hoặc error — nghĩa là dùng làm một step CI được ngay:

- name: Laravel health check
  run: php artisan doctor --format=github --fail-on=warn

--format=github biến kết quả thành annotation hiện thẳng trên giao diện GitHub Actions, còn --fail-on=warn siết chặt hơn: cảnh báo cũng đủ làm đỏ pipeline.

Nó không thay thế những gì

Đây là vòng khám tổng quát, không phải xét nghiệm chuyên sâu. Laravel Doctor không thay thế:

• Larastan / PHPStan — phân tích tĩnh chất lượng code.

• composer audit — tuy Doctor có nhóm check dependency audit, một quy trình bảo mật đầy đủ vẫn cần theo dõi CVE riêng.

• Security scanner và test suite — hai thứ này Doctor không chạm tới.

Về phiên bản: package yêu cầu PHP 8.3+ và Laravel 12 hoặc 13. Đang ở Laravel 10/11 thì chưa dùng được — thêm một lý do để cân nhắc nâng cấp.

Tóm lại

Thêm php artisan doctor vào ba chỗ là đủ có giá trị ngay: sau khi clone project về (đỡ mất buổi sáng onboarding), trong pipeline CI, và trước mỗi lần release. Chi phí gần bằng không, còn thứ nó bắt được thường là loại lỗi cấu hình chỉ lộ ra khi đã lên production.

Đọc thêm về hệ sinh thái Laravel trong bài Laravel Paper: dùng Markdown và JSON như Eloquent Models. Nếu phần database là chỗ bạn hay đau đầu, thử công cụ SQL → ERD để nhìn schema dưới dạng sơ đồ.