Filament: как подключить админ-панель к Laravel за час

К концу этого руководства у вас будет работающая админ-панель на Filament 3.x в проекте на Laravel 11: страница входа по адресу /admin, созданный админ-пользователь и CRUD для одной модели, который генерируется одной командой. На чистом проекте это занимает около часа, из которых половина уходит на установку зависимостей.

Filament — не единственный вариант (есть Laravel Nova за деньги, Backpack, самописная админка на Blade), но это самый быстрый способ получить панель без написания форм и таблиц руками. Здесь только установка и первый ресурс. Настройка ролей, кастомные виджеты и мультипанельность — отдельные темы, их не трогаем.

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

Проверьте окружение перед установкой. Если чего-то не хватает, вы узнаете об этом на середине установки, а не в самом начале.

• PHP 8.2 или выше — Filament 3 требует минимум 8.1, но Laravel 11 сам требует 8.2. Проверьте: php -v.
• Laravel 11.x — работающий проект с настроенным подключением к базе. Filament хранит своё состояние в вашей БД (пользователи), так что миграции должны проходить.
• Composer 2.x — composer -V.
• Расширения PHP: intl, gd или imagick (для загрузки и обработки изображений в панели). Без intl установка ругнётся сразу.
• Настроенный .env с рабочим соединением к базе — панель бесполезна, пока миграции не проходят.

Если проекта ещё нет, создайте его командой composer create-project laravel/laravel my-app и убедитесь, что php artisan migrate отрабатывает без ошибок.

Шаг 1. Установка пакета

Из корня проекта выполните:

composer require filament/filament:"^3.2" -W

Флаг -W (сокращение от --with-all-dependencies) разрешает Composer обновить смежные зависимости, если они конфликтуют. Установка тянет много пакетов (Livewire, Alpine, набор компонентов), так что займёт минуту-две.

Проверка: команда завершается строкой Generating optimized autoload files без красных ошибок, а в composer.json в секции require появилась строка filament/filament.

Шаг 2. Установка панели

Теперь разворачиваем саму панель — это создаёт провайдер и регистрирует маршруты:

php artisan filament:install --panels

Команда спросит идентификатор панели — по умолчанию admin, оставьте так. После этого появится файл app/Providers/Filament/AdminPanelProvider.php и он автоматически зарегистрируется в bootstrap/providers.php (в Laravel 11 провайдеры регистрируются именно там, а не в config/app.php).

Проверка: файл app/Providers/Filament/AdminPanelProvider.php существует, а в bootstrap/providers.php есть строка с AdminPanelProvider::class.

Шаг 3. Создание админ-пользователя

Панель по умолчанию использует модель App\Models\User. Создайте пользователя, под которым будете входить:

php artisan make:filament-user

Команда интерактивно спросит имя, e-mail и пароль. Она вставит запись напрямую в таблицу users, поэтому миграции к этому моменту должны быть применены (php artisan migrate).

Проверка: в консоли появится Success! ... may now log in at ... с адресом панели.

По умолчанию в панель пустит любого пользователя из таблицы users — Filament не знает, кто из них администратор. Пока проект локальный, это допустимо, но перед выкладкой в прод обязательно ограничьте доступ (см. раздел ниже).

Шаг 4. Первый вход

Запустите сервер разработки:

php artisan serve

Откройте в браузере http://127.0.0.1:8000/admin. Должна появиться страница входа Filament. Введите e-mail и пароль из шага 3 — попадёте в пустую панель с боковым меню и дашбордом.

Шаг 5. Ресурс для управления данными

Панель без данных бесполезна. Ресурс — это связка «модель + таблица + форма», которую Filament генерирует автоматически. Допустим, у вас есть модель App\Models\Post с миграцией. Сгенерируйте ресурс:

php artisan make:filament-resource Post --generate

Флаг --generate заставляет Filament прочитать структуру таблицы и сам расставить поля формы и колонки таблицы по типам столбцов. Без него получите пустые заготовки, которые придётся заполнять руками.

После генерации в меню панели появится пункт Posts. Перейдите в него — увидите таблицу записей, кнопку создания, формы редактирования и удаления. Всё это работает сразу, без единой написанной строки Blade.

Проверка: файлы появились в app/Filament/Resources/PostResource.php и папке app/Filament/Resources/PostResource/Pages/, а в панели работает создание и редактирование записей.

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

Самые частые проблемы на чистой установке:

• 404 Not Found на /admin — провайдер панели не зарегистрирован. Проверьте bootstrap/providers.php: там должна быть строка App\Providers\Filament\AdminPanelProvider::class. Если её нет — добавьте вручную и выполните php artisan optimize:clear.
• Class "IntlDateFormatter" not found или ошибка про intl при установке — не включено расширение PHP intl. Установите его для вашей версии PHP и перезапустите процесс.
• SQLSTATE[HY000] ... no such table: users при make:filament-user — не применены миграции. Выполните php artisan migrate и повторите создание пользователя.
• Страница входа открывается, но стили и скрипты не грузятся (голый HTML) — не опубликованы ассеты. Выполните php artisan filament:assets, а в проде добавьте эту команду в деплой.
• После --generate форма пустая — таблица модели ещё не создана или пустая. Ресурс читает структуру из реальной схемы БД, поэтому миграция модели должна быть применена до генерации.

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

Панель работает — теперь закройте два вопроса перед тем, как показывать её кому-то, кроме себя:

• Ограничьте доступ. Реализуйте метод canAccessPanel() в модели User через контракт FilamentUser — иначе в админку войдёт любой зарегистрированный пользователь. Точную сигнатуру метода и пример смотрите в разделе документации Filament про Users.
• Настройте деплой. В прод-окружении после каждого обновления выполняйте php artisan filament:assets и php artisan optimize, иначе панель может остаться без стилей.

Следующая тема после базовой панели — права и роли (через пакет вроде spatie/laravel-permission с интеграцией в Filament) и кастомизация форм ресурса. Но это уже за рамками первого запуска.