Аутентификация через Laravel Breeze: разбор на живом примере

Вы поставили свежий Laravel и вам нужен вход в систему: регистрация, логин, сброс пароля, защищённые маршруты. Laravel Breeze закрывает всё это одним пакетом и одной командой, после чего оставляет в проекте контроллеры, маршруты и шаблоны, которые можно читать и править руками. В этой статье разбираем, что именно Breeze кладёт в проект и как эти части связаны между собой на примере Laravel 11.x и Breeze 2.x. Не рассматриваем API-токены и SPA-сценарии на Sanctum — это отдельная тема; здесь только классическая сессионная аутентификация с рендерингом на сервере.

Что вообще делает Breeze

Breeze — это не runtime-библиотека, которая живёт в вашем приложении и что-то делает при каждом запросе. Это скаффолдинг¹: он один раз генерирует файлы прямо в вашем проекте и уходит. После установки вы редактируете обычные контроллеры и Blade-шаблоны, а сам пакет breeze больше не участвует в работе приложения. Это его ключевое отличие от Laravel Fortify, который остаётся бэкендом и прячет логику внутри пакета.

За аутентификацию отвечает не Breeze, а встроенные механизмы фреймворка: гвард web, провайдер users из config/auth.php, фасад Auth и middleware. Breeze лишь собирает из них готовый набор экранов и обработчиков.

Установка на живом проекте

Дальше — не отвлечённая теория, а последовательность на чистом приложении. Предполагаю, что у вас уже есть проект на Laravel 11.x, настроено подключение к базе в .env и выполнены миграции по умолчанию (таблица users создаётся стартовыми миграциями фреймворка).

Ставим пакет как dev-зависимость и запускаем установщик:

composer require laravel/breeze --dev
php artisan breeze:install

Установщик спросит стек. Для серверного рендеринга на Blade выбирайте вариант Blade. Если выберете стек с Vue или React, набор сгенерированных файлов будет другим — примеры ниже про Blade-стек.

После этого команда сама подтянет npm-зависимости и соберёт ассеты. Если она этого не сделала или вы прервали процесс, доберите руками:

npm install
npm run build
php artisan migrate

Точную актуальную последовательность и список стеков смотрите в разделе Starter Kits официальной документации — набор опций между версиями менялся.

Что появилось в проекте

Самое полезное — заглянуть, что именно Breeze добавил. Основное:

• routes/auth.php — все маршруты аутентификации, подключённые из routes/web.php;
• app/Http/Controllers/Auth/ — контроллеры регистрации, входа, сброса и подтверждения пароля, верификации почты;
• app/Http/Requests/Auth/LoginRequest.php — валидация и логика попытки входа;
• resources/views/auth/ — Blade-шаблоны форм;
• компоненты Blade в resources/views/components/ и layout в resources/views/layouts/.

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

Как устроен вход

Сердце логина — не контроллер, а form request. Контроллер AuthenticatedSessionController в методе store вызывает у объекта запроса метод authenticate(), а вся проверка живёт в LoginRequest. Упрощённо логика такая: запрос проверяет учётные данные через Auth::attempt(), а при неудаче бросает исключение валидации и учитывает ограничение частоты попыток через RateLimiter. После успешного входа контроллер регенерирует сессию — это защита от фиксации сессии:

// app/Http/Controllers/Auth/AuthenticatedSessionController.php (фрагмент)
public function store(LoginRequest $request): RedirectResponse
{
    $request->authenticate();

    // Новый идентификатор сессии после входа
    $request->session()->regenerate();

    return redirect()->intended(route('dashboard', absolute: false));
}

Обратите внимание на redirect()->intended(): если пользователя перекинуло на логин с защищённой страницы, после входа его вернёт туда, а не на дашборд по умолчанию.

Breeze не прячет логику входа в пакете. Она вся в вашем LoginRequest — открываете файл и видите, как именно проверяются данные и считаются попытки. Хотите двухфакторку или вход по коду — правите этот файл, а не боретесь с чужой абстракцией.

Как защищаются маршруты

Защита строится на middleware auth. В routes/web.php после установки появляется группа:

Route::middleware('auth')->group(function () {
    Route::get('/dashboard', function () {
        return view('dashboard');
    })->name('dashboard');
});

Middleware auth проверяет, вошёл ли пользователь через гвард web. Если нет — неавторизованного перенаправит на маршрут с именем login. Именно поэтому маршрут входа должен называться login: перенаправление по умолчанию завязано на это имя.

Проверка почты подключается middleware verified. Если хотите требовать подтверждённый email на дашборде, добавьте его в цепочку: Route::middleware(['auth', 'verified']). Но это сработает только если модель User реализует контракт MustVerifyEmail — по умолчанию в свежем проекте он закомментирован или отсутствует.

Где чаще всего спотыкаются

Разберём типичные проблемы с реальным текстом ошибок.

• После входа снова кидает на логин. Обычно причина — сессии. Проверьте SESSION_DRIVER в .env. Если стоит database, должна существовать таблица sessions (её создаёт отдельная миграция). Нет таблицы — сессия не сохраняется, и авторизация не держится между запросами.
• Формы без стилей, голый HTML. Значит, ассеты не собраны. Запустите npm run build и убедитесь, что в layout подключён @vite. При локальной разработке держите открытым npm run dev.
• Route [login] not defined. Маршруты аутентификации не подключены. Проверьте, что в routes/web.php есть строка require __DIR__.'/auth.php'; — установщик добавляет её сам, но при ручной правке файла её легко потерять.
• 419 Page Expired при отправке формы. Проблема с CSRF-токеном. Внутри тега <form> должна быть директива @csrf. Если она есть, а ошибка остаётся — истекла сессия или разошёлся домен и настройка SESSION_DOMAIN.
• Письма о сбросе пароля не приходят. В dev-окружении по умолчанию почта часто идёт в лог. Проверьте MAIL_MAILER: при значении log письмо со ссылкой сброса лежит в storage/logs/laravel.log, а не в почтовом ящике.

Breeze или его альтернативы

Breeze — не единственный вариант, и выбор влияет на то, где будет жить логика.

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

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

Первое — откройте LoginRequest и routes/auth.php и прочитайте их целиком: это займёт пять минут и снимет 90% вопросов о том, как что работает. Дальше настройте под проект три вещи: куда редиректить после входа (метод store контроллера сессии), нужна ли верификация почты (контракт MustVerifyEmail на модели и middleware verified) и реальную отправку писем в проде вместо драйвера log. Перед выкаткой проверьте лимит попыток входа в LoginRequest — значение по умолчанию стоит осознанно подтвердить под вашу нагрузку. Точные имена методов и опции установщика сверяйте с документацией вашей версии Laravel: между мажорными релизами структура стартовых наборов менялась.

¹ Скаффолдинг — автоматическая генерация заготовки кода (файлов, папок, шаблонов), которую разработчик дальше редактирует вручную, в отличие от библиотеки, чей код остаётся неизменным и вызывается во время работы приложения.