FilamentPHP: комплексное руководство по созданию админ-панелей в Laravel

автор Данила Справцев, Senior Web Developer

Filament стремительно завоёвывает популярность среди разработчиков Laravel благодаря своему удобному подходу к созданию административных панелей, управлению данными и интеграции динамических интерфейсов. В основе Filament лежат Livewire и Tailwind CSS, что позволяет существенно ускорить процесс разработки и работать без написания большого количества «чистого» JavaScript. В этой статье мы разберёмся, почему Filament стал таким востребованным решением, как его установить, какие ключевые модули и компоненты он предлагает, какие возможности открываются для опытных разработчиков, и в чём заключается его уникальность для бизнеса и для проектов любой сложности.


Что такое Filament и почему он так популярен?

В экосистеме Laravel есть разные инструменты для быстрого создания административных панелей. Filament выделяется на фоне конкурентов своей простотой и гибкостью. Он написан для Laravel, используя мощь Livewire, что обеспечивает реактивность интерфейса без классического подхода, основанного на Vue.js или React. Благодаря этому весь обмен данными и отрисовка происходят практически в реальном времени, но без необходимости обновлять страницу целиком.

Filament даёт возможность:

  • Генерировать CRUD-ресурсы (Create, Read, Update, Delete) всего несколькими командами.

  • Создавать формы с гибкой валидацией и пользовательскими полями.

  • Строить таблицы со сложными фильтрами, сортировкой и поиском.

  • Управлять ролями и правами доступа внутри админ-панели.

  • Расширять функциональность благодаря плагинам и кастомным компонентам.

Чем Filament отличается от других админ-панелей для Laravel?

Существует несколько популярных решений для быстрой сборки админ-панелей:

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

  • Backpack for Laravel – ориентирован на разработку классического CRUD-интерфейса на Bootstrap. Обычно лёгок в освоении, но может выглядеть «коробочным» при желании создать современный SPA-вариант.

  • Voyager – ещё одно известное решение, фокусируется на простом пользовательском интерфейсе и быстром MVP. Подходит для базовых задач, но требует более детальной настройки при усложнении проекта.

Filament выделяется за счёт «реактивного» подхода через Livewire и Tailwind CSS. Он:

  • Бесплатен и open-source, что удобно для любых проектов.

  • Имеет модульную структуру, позволяя интегрировать только нужные компоненты.

  • Позволяет быстро создавать динамические интерфейсы без погружения в JavaScript-фреймворки.

  • Хорошо документирован и имеет активное сообщество.


Установка и первичная настройка

Подготовка окружения

Прежде чем начать работу с Filament, убедитесь, что в вашем приложении Laravel настроена база данных и что оно соответствует необходимым требованиям по версии PHP и самим зависимостям фреймворка. Обычно это значит, что вы используете актуальную версию Laravel (8, 9, 10 и т.д.) и PHP не ниже 8.0 (или выше – в зависимости от актуальных требований Filament).

Установка через Composer

Установить Filament можно одной командой:

composer require filament/filament

Эта команда добавляет пакет Filament в ваш composer.json и загружает все необходимые зависимости.

Публикация ресурсов и конфигурация

После установки рекомендуется опубликовать файлы конфигурации, переводы и ресурсы, если это требуется в конкретной версии Filament:

php artisan vendor:publish --tag=filament-config
php artisan vendor:publish --tag=filament-assets

Файл конфигурации обычно располагается в config/filament.php. В нём вы можете настроить:

  • Путь к админ-панели (по умолчанию это /admin или /filament).

  • Средства аутентификации пользователей, которые будут иметь доступ к панели.

  • Общие настройки интерфейса, например, логотип, цветовую схему, язык по умолчанию.

Создание аккаунта администратора

Для входа в панель администрирования Filament необходим пользователь, имеющий соответствующие права. Как правило, в Laravel-проектах уже есть модель User (или вы можете создать свою). Дальше вы настраиваете Gate или Policy, разрешающие пользователю доступ к админ-панели. Самая простая логика — это назначить пользователю флаг is_admin, если такой столбец есть в базе, и проверять его при входе.


Архитектура Filament: компоненты и модули

Filament построен на наборе взаимосвязанных компонентов, которые упрощают разработку:

  • Resources (Ресурсы)
    Главная сущность для описания CRUD. Вы указываете, с какой моделью Eloquent работает ресурс, какие поля выводить в таблицах и формах, как фильтровать записи.

  • Pages (Страницы)
    Это отдельные страницы внутри админ-панели, не привязанные напрямую к CRUD-операциям. Можно использовать для дополнительных функций: интеграции с API, просмотра отчётов, управления задачами.

  • Widgets (Виджеты)
    Визуальные компоненты, которые могут отображать метрики, диаграммы, короткие списки данных или статистику. Виджеты можно размещать на главной странице панели или внутри ресурсов.

  • Forms (Формы)
    Форма — важнейший элемент управления данными. Filament предлагает гибкий синтаксис для создания полей разного типа: текст, число, дата, выбор из списка, загрузка файлов и многое другое.

  • Tables (Таблицы)
    Аналогично формам, таблицы представляют собой структуру для вывода данных из базы. Они поддерживают сортировку, фильтрацию, постраничный вывод (pagination).

  • Navigation (Навигация)
    Функционал для создания меню внутри админ-панели. Вы можете группировать ресурсы, назначать иконки, скрывать/показывать пункты меню при определённых условиях.


Работа с Filament Resources

Генерация ресурса

Наиболее типовой сценарий использования Filament — это создание CRUD для модели Eloquent. Достаточно выполнить:

php artisan make:filament-resource Product

Сгенерируется класс ProductResource, а также несколько файлов, которые отвечают за логику создания/редактирования (Create/Edit), просматривания (View) и удаление записей (Delete).

Файл Resource.php

Ключевой файл для ресурса обычно выглядит так:

<?php

namespace App\Filament\Resources;

use App\Models\Product;
use Filament\Resources\Resource;
use Filament\Forms;
use Filament\Tables;

class ProductResource extends Resource
{
    protected static ?string $model = Product::class;
    protected static ?string $navigationIcon = 'heroicon-o-shopping-cart';

    public static function form(Forms\Form $form): Forms\Form
    {
        return $form->schema([
            Forms\Components\TextInput::make('name')
                ->label('Название')
                ->required(),
            Forms\Components\TextInput::make('price')
                ->numeric()
                ->label('Цена')
                ->required(),
            Forms\Components\Textarea::make('description')
                ->label('Описание'),
        ]);
    }

    public static function table(Tables\Table $table): Tables\Table
    {
        return $table->columns([
            Tables\Columns\TextColumn::make('name')->label('Название'),
            Tables\Columns\TextColumn::make('price')->label('Цена'),
            Tables\Columns\TextColumn::make('created_at')->dateTime()->label('Дата создания'),
        ])
        ->filters([
            //
        ]);
    }

    public static function routes()
    {
        return [
            //
        ];
    }
}

В методе form() вы описываете структуру формы (схему полей), в методе table() — колонки для таблицы и дополнительные параметры (поиск, фильтрация). Filament автоматически генерирует маршруты для CRUD-операций, а также элементы навигации, если вы того пожелаете.

Настройка форм

Filament поддерживает множество типов компонентов форм:

  • TextInput (обычное текстовое поле или поле с числовой валидацией)

  • Textarea (многострочный ввод текста)

  • Select (выпадающий список, также может быть многозначным)

  • Toggle (переключатель «Да/Нет»)

  • FileUpload (загрузка одного или нескольких файлов, изображений)

  • DatePicker и DateTimePicker (выбор даты, времени)

  • RichEditor (текстовый редактор с форматированием)

  • Repeater (повторяющийся набор полей)

  • Builder (сложный конструктор для динамической структуры данных)

Это делает Filament универсальным инструментом: вы можете создавать от простых форм до продвинутых, состоящих из большого числа полей, со сложной бизнес-логикой.

Настройка таблиц

При работе с таблицами Filament Tables вы можете:

  • Указывать какие поля отображать и в каком порядке.

  • Добавлять фильтры (например, «Показать только товары со скидкой» или «Показать товары дороже 1000»).

  • Настраивать поиск по определённым столбцам.

  • Определять, как будет выглядеть колонка (например, форматировать цену или дату).

  • Включать массовые действия (bulk actions), позволяющие удалять сразу несколько записей или обновлять сразу группу товаров.

Таким образом, админ-панель получается интерактивной: администратор или менеджер может быстро находить нужные записи, сортировать их и изменять при необходимости.


Расширенные возможности: Pages, Widgets и темы оформления

Кастомные страницы (Pages)

Если базового CRUD-функционала недостаточно, вы можете создавать отдельные страницы, не привязанные к стандартным ресурсам. Применение:

  • Страница «Отчёты» с графиками продаж за день, неделю или месяц.

  • Страница «Управление задачами» для расписания или списка поручений.

  • Страница «Настройки системы» с изменением конфигураций, например, работы с внешними API.

Создаётся страница простой artisan-командой (имя и пространство имён настраиваются):

php artisan make:filament-page CustomPage

В результате появляется класс, где вы сами определяете логику: какие данные загружать, какие компоненты (формы, таблицы) выводить, как обрабатывать запросы.

Виджеты (Widgets)

Widgets — ещё один способ расширить функциональность: это мини-компоненты, которые могут выводить в панели администрирования любую информацию — графики, короткие отчёты, статистику и т.д. Для их создания есть отдельная команда artisan, после чего в классе виджета вы прописываете источники данных (Eloquent-запросы, внешние API), методы рендеринга и логику отображения.

Пример простого виджета для вывода количества пользователей:

<?php

namespace App\Filament\Widgets;

use Filament\Widgets\Widget;
use App\Models\User;

class UsersCountWidget extends Widget
{
    protected static string $view = 'filament.widgets.users-count-widget';

    public function getData(): array
    {
        return [
            'usersCount' => User::count(),
        ];
    }
}

В представлении users-count-widget.blade.php вы уже решаете, как именно показывать это число (текстом, иконкой или графиком).

Темизация и кастомизация интерфейса

Filament «из коробки» выглядит достаточно современно благодаря Tailwind CSS, но при желании вы можете изменить цветовую схему, шрифты или подключить собственные стили. Для этого есть несколько подходов:

  1. Использование конфигурационного файла: меняйте настройки filament.php, включая лого, favicon и основные цвета.

  2. Переопределение Tailwind: добавьте нужные цвета и классы в tailwind.config.js, а также поправьте стили, если вы собираете проект через Laravel Mix или Vite.

  3. Собственные Blade-шаблоны: вы можете переопределять файлы, опубликованные Filament’ом, если нужно уникальное оформление конкретных элементов интерфейса.

Благодаря гибкой архитектуре, Filament легко интегрируется в общий вид вашего приложения, не ощущаясь «инородным элементом».


Дополнительные настройки и тонкости использования

Аутентификация и авторизация

Для ограничения доступа к админ-панели используются стандартные механизмы Laravel:

  • Gates и Policies позволяют определить, какие действия может совершать пользователь.

  • В файле конфигурации Filament вы указываете политику, регулирующую вход в панель.

  • Можно использовать middleware (например, auth и admin) для дополнительной защиты роутов Filament.

Часто встречается сценарий, когда вся админ-панель доступна только администраторам с флагом is_admin = true. В более сложных проектах вы разграничиваете доступ к разным ресурсам по ролям: менеджер может редактировать товары, но не может управлять пользователями, и т.д.

Переводы и мультиязычность

Если вы делаете многоязычный проект, Filament предоставляет готовые инструменты для локализации. Базовые строки интерфейса можно перевести, опубликовав язык и корректируя файлы переводов. Поля форм тоже можно «подготовить» для разных языков: в зависимости от вашей архитектуры, это может быть либо отдельная модель переводов, либо прямое хранение полей в JSON-формате.

Взаимодействие с внешними сервисами

Filament не ограничивает вашу логику: в Pages, Widgets и Resources вы можете обращаться к любым внешним API, интегрировать платёжные системы, связывать ваши админ-инструменты с CRM. Это дополняет возможности классического Laravel, упрощая построение действительно продвинутых сервисов.

Производительность и нагрузка

Благодаря Livewire, обновления в интерфейсе происходят через AJAX-запросы, что сокращает объём передаваемых данных. Однако при сложных ресурсах и очень больших объёмах записей в базе (десятки или сотни тысяч) может потребоваться дополнительная оптимизация: индексы в базе, разделение тяжелых таблиц, кеширование результатов запросов. Filament сам по себе достаточно лёгкий, но всегда стоит помнить о грамотной архитектуре.


Плагины и экосистема Filament

Filament обладает активным сообществом. Разработчики публикуют плагины на GitHub или в Packagist, где встречаются:

  • Дополнительные поля форм (например, интеграция с WYSIWYG-редакторами, кастомные селекторы, диаграммы и т.п.).

  • Нестандартные таблицы с особыми фильтрами или расширенной функциональностью.

  • Расширения интеграции (Firebase, PayPal, Stripe и т.д.).

  • Готовые виджеты для статистики, дашборды.

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


Примеры использования Filament

Интернет-магазин

Представим, что вам нужно создать админ-панель для интернет-магазина, в котором есть товары, категории, заказы и пользователи. С Filament всё сводится к созданию ресурсов:

  1. ProductResource — управляет товарами (название, цена, описание, фото).

  2. CategoryResource — управляет категориями, их иерархией, привязками к товарам.

  3. OrderResource — позволяет просматривать и обновлять заказы (статус «Принят», «Отправлен», «Доставлен»).

  4. UserResource — при необходимости выводит список зарегистрированных пользователей.

Дополнительно создаёте DashboardPage, где в одном месте отображаете статистику по продажам, новым заказам, динамику. Для наглядности встраиваете виджеты с графиками и таблицами. Всё это делается без глубокого погружения во фронтенд-разработку — многие компоненты Filament настроены «из коробки».

CRM-система для отдела продаж

Если компания ведёт учёт сделок, контактов, встреч и финансовых операций, Filament можно использовать как основу для быстрой сборки CRM. Создав ресурсы для сущностей «Контрагент», «Сделка», «Счёт», «Событие» и настроив связи в Eloquent (hasMany, belongsToMany), вы получите удобную CRM-панель. Виджеты позволят выводить графики и метрики по конверсии сделок, а таблицы с фильтрами и поиском ускорят работу менеджеров.

Панель управления контентом (CMS)

Filament легко превращается в CMS-решение: ресурсы для статей, страниц, медиафайлов, с привязкой к категориям или тегам. Возможность интегрировать RichEditor делает редактирование контента удобным, а встроенные механизмы загрузки файлов (FileUpload) помогают при работе с изображениями или документами. При необходимости можно организовать предпросмотр страниц и внедрить версионность, если в проекте важна история правок.


Лучшие практики и советы

  • Держите код чистым: разделяйте бизнес-логику и методы Filament на соответствующие сервисы, чтобы не перегружать ресурсы.

  • Используйте Policies: настраивайте разные уровни доступа для пользователей в зависимости от их ролей.

  • Автоматизируйте тестирование: Laravel даёт удобный инструментарий для написания тестов, Filament при этом не мешает проверять CRUD и Pages.

  • Оптимизируйте работу с базой: применяйте жадную загрузку (Eager Loading) при выводе связанных данных, чтобы не получить «N+1» проблему.

  • Следите за обновлениями: Filament развивается активно. Релизы могут содержать не только новые функции, но и изменения в API, требующие адаптации вашего кода.

Последние статьи

Время от времени опыт трансформируется в текст и приобретает свое место на полке.

Время принимать решение - Готовы обсудить проект?