Аутентификация через Laravel Breeze: короткое руководство

Breeze — это стартовый набор аутентификации от команды Laravel. После установки у вас появятся страницы входа, регистрации, восстановления пароля, подтверждения email и профиля пользователя — на готовых контроллерах и маршрутах. Никакого написания форм и хеширования паролей вручную. В этом руководстве разберём установку на стеке Blade — самый быстрый путь, если вы не строите SPA. Весь процесс займёт 15-20 минут на чистом проекте.

Материал написан для Laravel 11.x и Breeze 2.x. Команды устанавливаются через пакетный менеджер composer и артизан-скрипт artisan. Если у вас Laravel 10 или ниже — часть путей отличается (в 11-й версии изменилась структура bootstrap/app.php и файлов конфигурации), об этом скажу отдельно.

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

Breeze ставится в уже существующий проект Laravel, а не создаёт его. Убедитесь, что у вас есть:

• PHP 8.2 или новее (требование Laravel 11);
• Composer, установленный глобально;
• Node.js 18+ и npm — Breeze компилирует CSS и JS через Vite;
• настроенное подключение к базе данных в файле .env — Breeze создаёт таблицу пользователей через миграции;
• чистый или свежий проект Laravel. На проекте со своей системой входа Breeze перезапишет часть файлов.

Проверить версию PHP: php -v. Проверить, что проект запускается: откройте его через php artisan serve и убедитесь, что стартовая страница отдаётся на http://127.0.0.1:8000.

Шаг за шагом

1. Установите пакет через Composer. В корне проекта выполните:

   composer require laravel/breeze --dev

   Флаг --dev ставит Breeze в dev-зависимости — в продакшене сам пакет не нужен, он только генерирует файлы. Проверка: в composer.json в секции require-dev появилась строка laravel/breeze.

2. Запустите установщик Breeze. Эта команда спросит, какой стек вы хотите:

   php artisan breeze:install

   В интерактивном меню выберите Blade with Alpine — вариант без сборки SPA. Дальше установщик спросит про тёмную тему и тестовый фреймворк (Pest или PHPUnit) — можно оставить значения по умолчанию. Проверка: в папке resources/views/auth появились файлы login.blade.php, register.blade.php и другие.

3. Установите и соберите фронтенд. Breeze добавил зависимости в package.json, их нужно поставить и скомпилировать:

   npm install
   npm run build

   Проверка: в папке public/build появился скомпилированный CSS и JS с манифестом. Для разработки удобнее держать открытым npm run dev — он пересобирает на лету.

4. Прогоните миграции. Breeze использует стандартную миграцию users, которая уже есть в Laravel, плюс добавляет таблицы для сессий и сброса паролей:

   php artisan migrate

   Если база пустая, artisan предложит создать её — согласитесь. Проверка: в базе появились таблицы users, password_reset_tokens и sessions.

5. Запустите сервер и проверьте страницы.

   php artisan serve

   Откройте http://127.0.0.1:8000/register. Зарегистрируйте тестового пользователя. После регистрации вас автоматически перекинет на /dashboard — значит, вход работает. Проверка: в таблице users появилась запись с вашим email и захешированным паролем.

Что именно сгенерировал Breeze

После установки в проекте появляются готовые маршруты аутентификации — они подключены через файл routes/auth.php, который Breeze добавляет и импортирует в routes/web.php. Контроллеры лежат в app/Http/Controllers/Auth. Вьюхи — в resources/views/auth. Всё это ваш код: правьте его как хотите, обновления Breeze их не тронут, потому что пакет только генерирует файлы один раз.

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

Как защитить свои маршруты

Готовый пример — маршрут /dashboard, доступный только вошедшим. Он обёрнут в middleware auth. Свой маршрут защищается так же:

// routes/web.php
Route::get('/orders', function () {
    return view('orders.index');
})->middleware('auth')->name('orders.index');

Если требуется ещё и подтверждённая почта, добавьте middleware verified: ->middleware(['auth', 'verified']). Тогда пользователь с неподтверждённым email получит редирект на страницу с просьбой подтвердить адрес.

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

• Vite manifest not found. Полный текст: Unable to locate file in Vite manifest. Вы не собрали фронтенд — выполните npm run build или запустите npm run dev в отдельном терминале.

• SQLSTATE[HY000] [2002] Connection refused. База не настроена или не запущена. Проверьте параметры DB_CONNECTION, DB_HOST, DB_DATABASE в .env и что СУБД поднята. После правки .env выполните php artisan config:clear.

• Class "Laravel\Breeze..." not found после установки. Команда breeze:install не видна артизану — забыли composer require или не обновился автозагрузчик. Выполните composer dump-autoload.

• Письма подтверждения и сброса пароля не приходят. По умолчанию Laravel 11 пишет письма в лог (MAIL_MAILER=log). Ищите тело письма и ссылку в storage/logs/laravel.log. Для реальной отправки настройте SMTP в .env.

• После входа 419 Page Expired. Проблема с CSRF-токеном или сессией. Проверьте, что в формах есть директива @csrf (в стандартных вьюхах Breeze она уже стоит), и что настроен APP_KEY — сгенерируйте его через php artisan key:generate, если он пуст.

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

Базовый вход работает — дальше настраивают под проект. Первым делом смотрите на подтверждение email: если оно вам нужно, класс User должен реализовывать интерфейс MustVerifyEmail — раскомментируйте его в модели. Дальше настраивают редирект после входа (константа в контроллерах Breeze) и почтовый транспорт для боевого окружения. Ограничение попыток входа Breeze уже включает через встроенный rate limiter — проверьте его лимиты, если ждёте высокую нагрузку на форму логина. Ролевую модель и права Breeze не даёт: для этого подключают отдельный пакет вроде spatie/laravel-permission или пишут свои Gate и Policy.

Если вам нужен API-токенный вход для мобильного приложения или SPA, Blade-стек Breeze не подойдёт — там смотрите в сторону API-стека Breeze или Laravel Sanctum. Это отдельная тема, здесь мы разобрали только серверный рендеринг на Blade.