На конференції Laracon US 2026 у Бостоні представили офіційний пакет Laravel Doctor, який додає команду artisan doctor для запуску перевірок здоров'я вашого додатка. За словами авторів, Artisan doctor виконує набір діагностичних перевірок Laravel-додатка: чи встановлено APP_KEY, чи відповідає версія PHP вимогам Composer, чи встановлено необхідні розширення і чи завершена конфігурація оточення. Там, де проблему можна виправити автоматично, інструмент це робить. Там, де не може - точно вказує, що саме не так.
Раніше діагностика зламаного Laravel-інсталу зазвичай означала перевірку ментального чеклісту: чи є файл .env, чи згенерований ключ, чи доступна для запису директорія storage/, чи не використовується з'єднання черги sync на продакшені. Doctor перетворює цей список у код і надає пакетам місце для додавання власних перевірок.
Як це працює
Кожна діагностика - це окремий клас, який перевіряє одну річ і повертає один із шести статусів: pass, notice, warn, fail, skip або error. За замовчуванням команда завершується з ненульовим статусом, якщо щось не вдається або виникають помилки. Якщо ви хочете, щоб попередження також провалювали збірку, передайте --fail-on=warn. Якщо потрібен лише звіт без коду помилки, використовуйте --fail-on=never.
Вбудований набір перевірок охоплює:
- Оточення: наявність
.env, APP_KEY, версія PHP відповідно до обмежень composer.json, необхідні та рекомендовані розширення, часова зона
- Composer: встановлені залежності, можливість створити оптимізовані файли автозавантаження, проблеми з
composer.lock, які можна виправити
- Конфігурація: завантаження та кешування конфігураційних файлів, встановлення значень, необхідних для активних драйверів, стан bootstrap-кешу
- База даних: доступність з'єднання за замовчуванням, існування файлу SQLite коли потрібно, незастосовані міграції
- Кеш, черги, планувальник та сесії: доступність налаштованих драйверів, перевірка Redis-з'єднань, виявлення заплановані завдань як нотатка
- Сховище: доступність диска за замовчуванням, можливість запису у необхідні директорії, існування симлінку
storage:link
- Безпека: відповідність режиму налагодження оточенню,
.env у gitignore, аудит залежностей
Оскільки деякі з цих речей не можна оцінити ізольовано, Doctor визначає ваш додаток в одному з двох режимів - local або production - і режим вирішує, чи є щось проблемою взагалі. З'єднання черги sync проходить перевірку локально і видає попередження на продакшені. Відсутні bootstrap-кеші попереджають на продакшені, але проходять локально, тоді як наявні кеші проходять на продакшені і видають нотатку локально, оскільки застарілий кеш - поширена причина того, що останні зміни не відображаються під час роботи. Laravel Doctor знає режими local, production та staging з коробки, і все, що він не розпізнає, оцінюється за стандартами продакшену.
Початок роботи
Встановіть пакет як dev-залежність:
composer require laravel/doctor --dev
Потім запустіть:
php artisan doctor
Коли діагностика, яка провалилася, може бути виправлена, Doctor повідомляє про проблему і запитує підтвердження перед будь-якими діями:
Storage is writable: The application cannot write to every required storage directory.
Make the storage directories writable? (yes/no) [yes]
Команда php artisan doctor --fix пропускає запит підтвердження. Вона може створити відсутній .env, згенерувати APP_KEY, вимкнути режим налагодження на продакшені, додати .env до .gitignore, створити публічний symlink сховища та виправити права доступу до директорій storage. Інші виправлення вимагають від людини вибору серед варіантів, наприклад, на яке сховище кешу перемкнутися, коли стандартне недоступне. Такі варіанти показуються як список вибору при інтерактивному запуску команди і перетворюються на звичайні помилки при --fix.
Діагностики можна фільтрувати за назвою класу, групою, пакетом або маскою пакета:
php artisan doctor --only=security
php artisan doctor --except=laravel/
Якщо ви завжди хочете застосовувати однакові селектори, опублікуйте конфігураційний файл командою php artisan vendor:publish --tag=doctor-config і встановіть їх там.
Власні діагностики
Пакети можуть реєструвати діагностики зі свого service provider через фасад Doctor, так само як це робив би додаток:
use Laravel\Doctor\Facades\Doctor;
use Vendor\Package\Diagnostics\HorizonIsRunning;
public function boot(): void
{
Doctor::diagnostic(HorizonIsRunning::class);
}
Звіти показують, з якого Composer-пакета походить кожна діагностика:
[fail] Storage is writable (laravel/doctor): The application cannot write to every required storage directory.
[pass] SQLite database exists (acme/application): The SQLite database file exists.
[warn] Horizon is running (laravel/horizon): Horizon is not currently running.
Запуск php artisan make:diagnostic HorizonIsRunning створює шаблон у app/Doctor/Diagnostics. Він розширює Laravel\Doctor\Diagnostic і реалізує метод check(), який повертає DiagnosticResult. Текст повідомлень живе окремо в методі messages(), де кожен Message::make() містить резюме, текст виправлення, посилання на документацію та запит підтвердження, показаний перед виконанням виправлення.
Якщо ваша перевірка може виправити те, що знайшла, реалізуйте Laravel\Doctor\Contracts\Fixable і позначте конкретні помилки як ->fixable(). Цей метод також приймає EnvironmentMode, тому виправлення можна обмежити машиною розробника.
Вивід для CI та AI-агентів
Вивід у CLI є стандартним, але --format=json створює машиночитаний звіт, а --format=github - анотації GitHub Actions. Doctor відхиляє --fix з обома цими форматами, тому звіт для машини ніколи не змінює додаток.
Існує четвертий формат, орієнтований на coding-агентів, і Doctor автоматично перемикається на нього, коли Laravel Agent Detector виявляє, що він працює всередині чогось на кшталт Claude Code або Cursor. Він слідує конвенції Laravel PAO: один рядок JSON, підрахунки на початку, і лише результати, на які можна діяти, деталізовані.
{"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}]}
Це підводить до решти оголошення: пакети можуть реєструвати власні діагностичні перевірки, тому пакет зі специфічними вимогами конфігурації може підключитися безпосередньо до artisan doctor і показувати власні перевірки здоров'я поряд із фреймворковими. Це також природний останній крок для AI-агентів програмування: після внесення змін агент може запустити artisan doctor як фінальну перевірку на вменяємість перед тим, як вважати завдання виконаним.
Все, що позначено як fixable, може бути очищене повторним запуском з --fix, який застосовує виправлення, повторно запускає діагностики та додає результати до payload. Все, що повертається з картою options, потребує вибору, який --fix не зробить самостійно, і там агент має або слідувати тексту виправлення самостійно, або передати короткий список людині. Щоб побачити формат без агента, запустіть AI_AGENT=test php artisan doctor.
Doctor також може працювати без Artisan-команди. Doctor::run() повертає DiagnosticReport, а only(), except(), bail() та fixUsing() обмежують запуск програмно.
Дізнатися більше
Laravel Doctor вимагає PHP 8.3 і Laravel 12 або 13, розповсюджується під ліцензією MIT. Повна документація, включаючи діагностичні помічники в Laravel\Doctor\Support і повний посібник зі створення власних перевірок, доступна в репозиторії Laravel Doctor на GitHub.
