Laravel Breeze: что нужно знать до установки аутентификации

Laravel Breeze ставит рабочую аутентификацию — регистрацию, вход, восстановление пароля, подтверждение email и смену пароля в профиле — примерно за пять минут. В конце у вас будут готовые маршруты, контроллеры и шаблоны, которые можно редактировать под себя. Статья про то, что нужно иметь и решить до запуска php artisan breeze:install, чтобы не переустанавливать пакет из-за неправильно выбранного стека.

Актуально для Laravel 11.x и 12.x и Breeze 2.x. В более старых версиях (Laravel 9–10) команды те же, но набор стеков и структура файлов немного отличаются — сверяйтесь с документацией под вашу версию.

Что нужно иметь до начала

Breeze — не самостоятельное приложение, а слой поверх свежего Laravel. Проверьте, что на месте всё из списка, иначе установка либо упадёт, либо оставит наполовину настроенный проект.

• PHP 8.2 или новее — минимум для Laravel 11/12. Проверьте php -v.
• Composer — Breeze ставится как dev-зависимость через него.
• Готовый проект Laravel: composer create-project laravel/laravel my-app. Breeze в чистое место не устанавливают.
• Настроенная база данных в .env и выполненные миграции. Breeze опирается на таблицу users, которая приезжает со стартовыми миграциями Laravel.
• Node.js и npm — фронтенд Breeze собирается через Vite. Без сборки страницы входа откроются без стилей.

Отдельно про базу: если вы выбрали SQLite (в новых версиях Laravel это дефолт), файл database/database.sqlite должен существовать. Для MySQL или PostgreSQL сначала создайте саму базу и пропишите доступы, потом ставьте Breeze.

Выбор стека — решение, которое трудно отменить

Главный вопрос при установке: breeze:install спросит, какой фронтенд-стек вы хотите. Ответ определяет, какие шаблоны и зависимости попадут в проект, и переиграть его потом — значит вычистить сгенерированные файлы вручную. Поэтому выбирайте осознанно.

Стек API не отдаёт вам HTML-страницы вовсе — он рассчитан на связку с внешним SPA. Если вы ждали форму входа в браузере, а получили голые JSON-эндпоинты, вы просто выбрали не тот вариант.

Breeze задуман как отправная точка, а не как готовый продукт. Всё, что он генерирует, лежит в вашем репозитории и предназначено для правки — это не спрятанный в вендоре код.

Установка по шагам

1. Установите пакет как dev-зависимость:

   composer require laravel/breeze --dev

   Проверка: в composer.json в блоке require-dev появится laravel/breeze.

2. Запустите установщик и выберите стек в интерактивном меню:

   php artisan breeze:install

   Команда спросит про стек, про темную тему и про набор для тестов (Pest или PHPUnit). Стрелками выберите нужное, подтвердите Enter. Проверка: в routes/ появится auth.php, а в app/Http/Controllers/Auth/ — контроллеры входа и регистрации.

3. Примените миграции — стартовые таблицы Laravel, включая users:

   php artisan migrate

   Проверка: команда выведет строки вида DONE для каждой миграции. Если увидите ошибку подключения — вернитесь к настройке .env.

4. Установите фронтенд-зависимости и запустите сборку:

   npm install
   npm run dev

   Проверка: Vite поднимет dev-сервер и не будет ругаться на отсутствующие модули. Держите этот процесс запущенным во время разработки.

5. В отдельном терминале поднимите приложение:

   php artisan serve

   Проверка: откройте http://127.0.0.1:8000/register — должна появиться оформленная форма регистрации. Зарегистрируйтесь и убедитесь, что вас перебросило на /dashboard.

Если не получилось

• Страница входа без стилей, в консоли ошибки загрузки ресурсов. Не запущен Vite. Выполните npm run dev для разработки или npm run build для продакшена — иначе Blade-шаблоны ссылаются на несобранные ассеты.

• SQLSTATE[HY000] [1049] Unknown database или could not find driver. База не создана либо в PHP не включено нужное расширение (pdo_mysql, pdo_pgsql, pdo_sqlite). Создайте базу, проверьте .env и включённые расширения через php -m.

• Table 'users' doesn't exist при попытке входа. Не выполнены миграции. Запустите php artisan migrate.

• Письмо о сбросе пароля или подтверждении не приходит. В свежем проекте почта часто настроена на драйвер log — письмо не отправляется, а пишется в storage/logs/laravel.log. Для реальной отправки настройте SMTP в .env.

• Ссылка подтверждения email ведёт в никуда. Проверка почты работает, только если ваша модель User реализует интерфейс MustVerifyEmail. Breeze генерирует маршруты, но включить интерфейс в модели нужно самостоятельно.

Что решить заранее, чтобы не переделывать

Три вопроса лучше закрыть до установки, а не после запуска в бой.

• Нужна ли проверка email. Если да — заложите SMTP и добавьте MustVerifyEmail в модель User сразу, пока не появились пользователи без подтверждённой почты.
• Стек не переигрывается легко. Смена, например, с Blade на Inertia после установки — это ручная чистка контроллеров, шаблонов и зависимостей. Определитесь с фронтендом до breeze:install.
• Breeze или Jetstream. Breeze даёт базовую аутентификацию и точку для доработки. Если нужны двухфакторка, управление сессиями и командами из коробки — это Jetstream, отдельный пакет. Начинать проект под будущий 2FA на Breeze, чтобы потом мигрировать, — лишняя работа.

Что делать дальше

После рабочей формы входа настройте отправку почты через реальный SMTP и проверьте сброс пароля от начала до конца — на живом почтовом ящике, а не по логу. Затем решите, как разграничивать доступ: middleware auth уже навешен на маршруты дашборда, но роли и права Breeze не даёт — под это берут отдельный пакет вроде spatie/laravel-permission. Настройка двухфакторной аутентификации — отдельная тема; на Breeze её из коробки нет, здесь мы разбираем только базовый вход.