Laravel Doctor: діагностуйте свій застосунок однією командою Artisan

На конференції Laracon US 2026 у Бостоні анонсували Laravel Doctor — новий інструмент, що додає команду artisan doctor для комплексної перевірки стану вашого застосунку. З офіційного анонсу:

Artisan doctor виконує серію health checks вашого Laravel-застосунку: чи встановлено APP_KEY, чи відповідає версія PHP вимогам Composer, чи наявні необхідні розширення та чи коректно налаштоване оточення. Там, де проблему можна виправити автоматично, інструмент це робить. В іншому разі — чітко вказує, що саме пішло не так.

Раніше діагностика несправної інсталяції Laravel зазвичай зводилася до перевірки внутрішнього чеклиста: чи є файл .env, чи згенеровано ключ, чи доступна директорія storage/ для запису та чи не встановлено драйвер черги sync у продакшені. Doctor перетворює цей список на код і дає можливість розробникам пакетів додавати власні перевірки.

# Як це працює

Кожна діагностика — це окремий клас, який перевіряє певний аспект і повертає один із шести статусів: pass, notice, warn, fail, skip або error. За замовчуванням команда завершується з ненульовим кодом помилки, якщо виявлено fail або error. Якщо ви хочете, щоб білд зупинявся і на попередженнях, використовуйте прапор --fail-on=warn. Якщо ж вам потрібен лише звіт без зупинки процесу — --fail-on=never.

Стандартний набір перевірок охоплює:

• Оточення: наявність .env, APP_KEY, відповідність версії PHP обмеженням composer.json, наявність рекомендованих розширень та часовий пояс.
• Composer: чи встановлені залежності, чи оптимізовано автозавантаження та чи є помилки у composer.lock, які можна виправити.
• Конфігурація: завантаження та кешування конфігураційних файлів, наявність значень для активних драйверів та стан bootstrap-кешу.
• База даних: доступність стандартного з’єднання, наявність файлу SQLite (якщо потрібно) та статус міграцій.
• Кеш, черги, планувальник та сесії: доступність драйверів, перевірка з’єднань Redis; заплановані завдання відображаються як notice.
• Сховище: доступність дисків, права на запис у директорії та наявність симлінка storage:link.
• Безпека: відповідність режиму debug поточному оточенню, наявність .env у .gitignore та аудит вразливостей залежностей.

Деякі параметри неможливо оцінити ізольовано, тому Doctor визначає режим роботи застосунку: local або production. Наприклад, драйвер черги sync вважається нормальним для локальної розробки, але викликає warn у продакшені. Відсутність кешу bootstrap у продакшені — це попередження, тоді як його наявність під час локальної розробки викличе notice, адже застарілий кеш часто є причиною того, що нові зміни не відображаються. 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, вимкнути debug mode у продакшені, додати .env до .gitignore, створити публічний симлінк та виправити права доступу до папок. Деякі виправлення потребують вибору від користувача (наприклад, на яке сховище переключитися, якщо основне недоступне) — у такому разі при запуску --fix Doctor просто повідомить про помилку.

Діагностики можна фільтрувати за назвою класу, групою або пакетом:

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

Щоб зберегти ці налаштування, опублікуйте файл конфігурації за допомогою php artisan vendor:publish --tag=doctor-config.

# Власні діагностики

Пакети можуть реєструвати власні перевірки у своїх service providers через фасад Doctor:

use Laravel\Doctor\Facades\Doctor;
use Vendor\Package\Diagnostics\HorizonIsRunning;
 
public function boot(): void
{
    Doctor::diagnostic(HorizonIsRunning::class);
}

У звіті буде вказано, з якого саме пакета надійшла перевірка:

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

Для автоматичного виправлення помилок реалізуйте інтерфейс Laravel\Doctor\Contracts\Fixable і позначте відповідні результати методом ->fixable(). Цей метод також приймає EnvironmentMode, що дозволяє обмежити автоматичні виправлення лише локальною машиною розробника.

# Вивід для CI та ШІ-агентів

Окрім звичайного CLI-формату, Doctor підтримує --format=json для машинного зчитування та --format=github для анотацій у GitHub Actions. У цих режимах --fix не працює, щоб уникнути неочікуваних змін у застосунку під час автоматизації.

Також є спеціальний четвертий формат для ШІ-агентів. 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. Це також логічний фінальний крок для ШІ-агентів: після внесення змін агент може запустити artisan doctor як фінальну перевірку працездатності завдання.

Усе, що позначено як fixable, ШІ-агент може виправити повторним запуском із прапором --fix. Якщо ж для виправлення потрібен вибір із кількох варіантів (масив options), агент має або слідувати текстовій інструкції, або надати вибір людині. Щоб протестувати цей формат вручну, запустіть AI_AGENT=test php artisan doctor.

Doctor також можна використовувати програмно без Artisan-команди через Doctor::run(), використовуючи методи only(), except(), bail() та fixUsing().

# Дізнатися більше

Laravel Doctor потребує PHP 8.3 та Laravel 12 або 13 і розповсюджується за ліцензією MIT. Повна документація, включно з хелперами у Laravel\Doctor\Support та гайдом зі створення власних перевірок, доступна у репозиторії на GitHub.