ПОЧАТОК · ПЕРЕКЛАДЕНО оновлено 20 вересня 2026

Налаштування панелі · Filament

Вступ

За замовчуванням файл конфігурації лежить у app/Providers/Filament/AdminPanelProvider.php. Читайте далі, щоб дізнатися більше про панелі і про те, чому кожна з них має власний файл конфігурації.

Знайомство з панелями

Після встановлення пакета для вас уже налаштована одна панель, і вона живе на /admin. Усі ресурси, власні сторінки й віджети дашборду, які ви створюєте, реєструються саме в цій панелі.

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

Наприклад, ви можете зробити панель, де користувачі входять на /app і бачать свій дашборд, а адміністратори входять на /admin і керують застосунком. Панель /app і панель /admin мають власні ресурси, бо в кожної групи користувачів свої потреби. Filament дає змогу це зробити, надаючи можливість створювати кілька панелей.

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

Коли ви запускаєте filament:install, у теці app/Providers/Filament створюється новий файл - AdminPanelProvider.php. Цей файл містить конфігурацію панелі /admin.

Коли в документації йдеться про «конфігурацію», мається на увазі саме той файл, який вам потрібно редагувати. Він дозволяє повністю налаштувати застосунок під себе.

Створення нової панелі

Щоб створити нову панель, скористайтеся командою make:filament-panel, передавши унікальну назву нової панелі:

php artisan make:filament-panel app

Ця команда створить нову панель з назвою «app». Файл конфігурації буде створено за шляхом app/Providers/Filament/AppPanelProvider.php. Доступ до цієї панелі можна отримати за адресою /app, але ви можете змінити шлях, якщо такий вас не влаштовує.

Оскільки цей файл конфігурації є також сервіс-провайдером Laravel, його потрібно зареєструвати у bootstrap/providers.php (структура застосунку Laravel 11 і новіших) або в config/app.php (структура застосунку Laravel 10 і старіших). Filament спробує зробити це за вас, але якщо при спробі відкрити панель ви отримуєте помилку, то цей процес, найімовірніше, не спрацював.

Зміна шляху

У файлі конфігурації панелі ви можете змінити шлях, за яким доступний застосунок, за допомогою методу path():

use Filament\Panel;

public function panel(Panel $panel): Panel
{
    return $panel
        // ...
        ->path('app');
}

Якщо ви хочете, щоб застосунок був доступний без жодного префікса, задайте порожній рядок:

use Filament\Panel;

public function panel(Panel $panel): Panel
{
    return $panel
        // ...
        ->path('');
}

Переконайтеся, що ваш файл routes/web.php ще не визначає маршрут '' або '/', бо він матиме пріоритет.

Render hooks

Render hooks дозволяють рендерити Blade-вміст у різних точках представлень фреймворку. Ви можете зареєструвати глобальні render hooks у сервіс-провайдері чи middleware, але так само можна зареєструвати render hooks, специфічні для панелі. Для цього використовуйте метод renderHook() на обʼєкті конфігурації панелі. Ось приклад інтеграції wire-elements/modal з Filament:

use Filament\Panel;
use Filament\View\PanelsRenderHook;
use Illuminate\Support\Facades\Blade;

public function panel(Panel $panel): Panel
{
    return $panel
        // ...
        ->renderHook(
            PanelsRenderHook::BODY_START,
            fn (): string => Blade::render('@livewire(\'livewire-ui-modal\')'),
        );
}

Повний перелік доступних render hooks можна знайти тут.

Встановлення домену

За замовчуванням Filament відповідає на запити з усіх доменів. Якщо ви хочете обмежити його конкретним доменом, скористайтеся методом domain(), аналогічним до Route::domain() у Laravel:

use Filament\Panel;

public function panel(Panel $panel): Panel
{
    return $panel
        // ...
        ->domain('admin.example.com');
}

Налаштування максимальної ширини вмісту

За замовчуванням Filament обмежує ширину вмісту сторінки, щоб він не розтягувався надто широко на великих екранах. Щоб це змінити, використайте метод maxContentWidth(). Значення відповідають шкалі max-width у Tailwind. Доступні варіанти: ExtraSmall, Small, Medium, Large, ExtraLarge, TwoExtraLarge, ThreeExtraLarge, FourExtraLarge, FiveExtraLarge, SixExtraLarge, SevenExtraLarge, Full, MinContent, MaxContent, FitContent, Prose, ScreenSmall, ScreenMedium, ScreenLarge, ScreenExtraLarge і ScreenTwoExtraLarge. За замовчуванням - SevenExtraLarge:

use Filament\Panel;
use Filament\Support\Enums\Width;

public function panel(Panel $panel): Panel
{
    return $panel
        // ...
        ->maxContentWidth(Width::Full);
}

Якщо ви хочете задати максимальну ширину вмісту для сторінок типу SimplePage, як-от сторінки входу й реєстрації, скористайтеся методом simplePageMaxContentWidth(). За замовчуванням - Large:

use Filament\Panel;
use Filament\Support\Enums\Width;

public function panel(Panel $panel): Panel
{
    return $panel
        // ...
        ->simplePageMaxContentWidth(Width::Small);
}

Позиція підменю навігації за замовчуванням

Підменю навігації за замовчуванням рендериться на початку кожної сторінки. Його можна налаштувати окремо для сторінки, ресурсу та кластера, але також можна задати одразу для всієї панелі через метод subNavigationPosition(). Значенням може бути SubNavigationPosition::Start, SubNavigationPosition::End або SubNavigationPosition::Top, щоб відрендерити підменю у вигляді вкладок:

use Filament\Pages\Enums\SubNavigationPosition;
use Filament\Panel;

public function panel(Panel $panel): Panel
{
    return $panel
        // ...
        ->subNavigationPosition(SubNavigationPosition::End);
}

Хуки життєвого циклу

Хуки дозволяють виконувати код протягом життєвого циклу панелі. bootUsing() - це хук, який виконується на кожному запиті в межах цієї панелі. Якщо панелей кілька, виконається лише bootUsing() поточної панелі. Функція запускається з middleware, після того як завантажено всі сервіс-провайдери:

use Filament\Panel;

public function panel(Panel $panel): Panel
{
    return $panel
        // ...
        ->bootUsing(function (Panel $panel) {
            // ...
        });
}

Режим SPA

Режим SPA використовує можливість wire:navigate у Livewire, щоб ваша панель, відрендерена на сервері, відчувалася як single-page-application: менша затримка між завантаженнями сторінок і смужка завантаження для довших запитів. Щоб увімкнути режим SPA для панелі, скористайтеся методом spa():

use Filament\Panel;

public function panel(Panel $panel): Panel
{
    return $panel
        // ...
        ->spa();
}

Вимкнення SPA-навігації для окремих URL

За замовчуванням, коли ввімкнено режим SPA, будь-який URL на тому самому домені, що й поточний запит, відкривається через можливість Livewire wire:navigate. Якщо ви хочете вимкнути це для окремих URL, скористайтеся методом spaUrlExceptions():

use App\Filament\Resources\Posts\PostResource;
use Filament\Panel;

public function panel(Panel $panel): Panel
{
    return $panel
        // ...
        ->spa()
        ->spaUrlExceptions(fn (): array => [
            url('/admin'),
            PostResource::getUrl(),
        ]);
}

У цьому прикладі ми викликаємо getUrl() на ресурсі, щоб отримати URL сторінки-списку цього ресурсу. Ця можливість вимагає, щоб панель уже була зареєстрована, а конфігурація виконується надто рано в життєвому циклі запиту. Замість цього ви можете повернути URL з функції, яка виконається після реєстрації панелі.

Ці URL мають точно збігатися з URL, на який переходить користувач, включно з доменом і протоколом. Якщо ви хочете зіставляти кілька URL за шаблоном, використовуйте зірочку (*) як символ підстановки:

use Filament\Panel;

public function panel(Panel $panel): Panel
{
    return $panel
        // ...
        ->spa()
        ->spaUrlExceptions([
            '*/admin/posts/*',
        ]);
}

Увімкнення попереднього завантаження в режимі SPA

Попереднє завантаження (prefetching) у режимі SPA покращує досвід користувача, автоматично завантажуючи сторінки при наведенні на посилання, завдяки чому навігація відчувається ще швидшою. Ця можливість спирається на функціональність wire:navigate.hover у Livewire.

Щоб увімкнути режим SPA з попереднім завантаженням, передайте параметр hasPrefetching: true у метод spa():

use Filament\Panel;

public function panel(Panel $panel): Panel
{
    return $panel
        // ...
        ->spa(hasPrefetching: true);
}

Коли попереднє завантаження ввімкнено, всі посилання у вашій панелі автоматично отримують wire:navigate.hover, який підвантажує вміст сторінки при наведенні на посилання. Це без проблем працює разом із винятками для URL: будь-які URL, виключені з режиму SPA, також виключаються з попереднього завантаження.

Попереднє завантаження працює лише за ввімкненого режиму SPA. Якщо ви вимкнете режим SPA, попереднє завантаження теж вимкнеться автоматично.

Попереднє завантаження важких сторінок може збільшити витрати трафіку й навантаження на сервер, особливо якщо користувачі швидко наводять курсор на багато посилань поспіль. Використовуйте цю можливість розважливо, надто якщо у вашому застосунку є сторінки з великими обсягами даних або складними запитами.

Попередження про незбережені зміни

Ви можете попереджати користувачів, якщо вони намагаються піти зі сторінки, не зберігши змін. Це працює на сторінках ресурсу Create та Edit, а також у будь-яких відкритих модальних вікнах дій. Щоб увімкнути цю можливість, скористайтеся методом unsavedChangesAlerts():

use Filament\Panel;

public function panel(Panel $panel): Panel
{
    return $panel
        // ...
        ->unsavedChangesAlerts();
}

Модальні вікна дій із вимкненою схемою, як-от модальне вікно ViewAction, доступне лише для читання, попередження не викликають. Ви також можете вимкнути попередження для іншої дії, яка не може містити незбережених змін, методом unsavedChangesAlert(false).

Увімкнення транзакцій бази даних

За замовчуванням Filament не загортає операції в транзакції бази даних і дає користувачеві увімкнути це самостійно, коли він перевірив, що його операції безпечно загортати в транзакцію. Проте ви можете увімкнути транзакції бази даних одразу для всіх операцій методом databaseTransactions():

use Filament\Panel;

public function panel(Panel $panel): Panel
{
    return $panel
        // ...
        ->databaseTransactions();
}

Для дій, які ви не хочете загортати в транзакцію, використовуйте метод databaseTransaction(false):

CreateAction::make()
    ->databaseTransaction(false)

А для сторінок на кшталт Create resource і Edit resource задайте властивості $hasDatabaseTransactions значення false у класі сторінки:

use Filament\Resources\Pages\CreateRecord;

class CreatePost extends CreateRecord
{
    protected ?bool $hasDatabaseTransactions = false;

    // ...
}

Увімкнення транзакцій бази даних для окремих дій і сторінок

Замість того щоб вмикати транзакції бази даних усюди й вимикати їх для окремих дій і сторінок, ви можете вмикати транзакції лише для конкретних дій і сторінок.

Для дій скористайтеся методом databaseTransaction():

CreateAction::make()
    ->databaseTransaction()

Для сторінок на кшталт Create resource і Edit resource задайте властивості $hasDatabaseTransactions значення true у класі сторінки:

use Filament\Resources\Pages\CreateRecord;

class CreatePost extends CreateRecord
{
    protected ?bool $hasDatabaseTransactions = true;

    // ...
}

Реєстрація ассетів для панелі

Ви можете зареєструвати ассети, які завантажуватимуться лише на сторінках конкретної панелі, а не в решті застосунку. Для цього передайте масив ассетів у метод assets():

use Filament\Panel;
use Filament\Support\Assets\Css;
use Filament\Support\Assets\Js;

public function panel(Panel $panel): Panel
{
    return $panel
        // ...
        ->assets([
            Css::make('custom-stylesheet', resource_path('css/custom.css')),
            Js::make('custom-script', resource_path('js/custom.js')),
        ]);
}

Перш ніж ці ассети можна буде використовувати, вам потрібно виконати php artisan filament:assets.

Застосування middleware

Ви можете застосувати додаткові middleware до всіх маршрутів, передавши масив класів middleware у метод middleware() у конфігурації:

use Filament\Panel;

public function panel(Panel $panel): Panel
{
    return $panel
        // ...
        ->middleware([
            // ...
        ]);
}

За замовчуванням middleware виконуються під час першого завантаження сторінки, але не на наступних AJAX-запитах Livewire. Якщо ви хочете виконувати middleware на кожному запиті, зробіть їх постійними, передавши true другим аргументом методу middleware():

use Filament\Panel;

public function panel(Panel $panel): Panel
{
    return $panel
        // ...
        ->middleware([
            // ...
        ], isPersistent: true);
}

Застосування middleware до автентифікованих маршрутів

Ви можете застосувати middleware до всіх автентифікованих маршрутів, передавши масив класів middleware у метод authMiddleware() у конфігурації:

use Filament\Panel;

public function panel(Panel $panel): Panel
{
    return $panel
        // ...
        ->authMiddleware([
            // ...
        ]);
}

use Filament\Panel;

public function panel(Panel $panel): Panel
{
    return $panel
        // ...
        ->authMiddleware([
            // ...
        ], isPersistent: true);
}

Вимкнення трансляції подій

За замовчуванням Laravel Echo автоматично підключається для кожної панелі, якщо облікові дані задані в опублікованому файлі конфігурації config/filament.php. Щоб вимкнути це автоматичне підключення в панелі, скористайтеся методом broadcasting(false):

use Filament\Panel;

public function panel(Panel $panel): Panel
{
    return $panel
        // ...
        ->broadcasting(false);
}

Строгий режим авторизації

За замовчуванням, авторизуючи доступ користувача до ресурсу, Filament спершу перевіряє, чи існує політика для цієї моделі, і якщо так, перевіряє, чи є в політиці метод для виконання дії. Якщо політики або методу політики немає, доступ до ресурсу надається, бо припускається, що ви ще не налаштували авторизацію або вона вам не потрібна.

Якщо ви хочете, щоб Filament натомість кидав виняток за відсутності політики чи методу політики, увімкніть строгий режим авторизації методом strictAuthorization():

use Filament\Panel;

public function panel(Panel $panel): Panel
{
    return $panel
        // ...
        ->strictAuthorization();
}

Налаштування сповіщень про помилки

Коли режим налагодження Laravel вимкнено, Filament замінює повноекранні модальні вікна помилок Livewire на акуратніші flash-сповіщення. Вимкнути цю поведінку можна методом errorNotifications(false):

use Filament\Panel;

public function panel(Panel $panel): Panel
{
    return $panel
        // ...
        ->errorNotifications(false);
}

Текст сповіщення про помилку можна змінити, передавши рядки в параметри title і body методу registerErrorNotification():

use Filament\Panel;

public function panel(Panel $panel): Panel
{
    return $panel
        // ...
        ->registerErrorNotification(
            title: 'An error occurred',
            body: 'Please try again later.',
        );
}

Ви також можете зареєструвати текст сповіщення для конкретного HTTP-статусу, наприклад 404, передавши цей код статусу в параметрі statusCode:

use Filament\Panel;

public function panel(Panel $panel): Panel
{
    return $panel
        // ...
        ->registerErrorNotification(
            title: 'An error occurred',
            body: 'Please try again later.',
        )
        ->registerErrorNotification(
            title: 'Record not found',
            body: 'A record you are looking for does not exist.',
            statusCode: 404,
        );
}

Ви також можете приховати сповіщення для конкретного HTTP-статусу, наприклад 403, передавши цей код статусу в метод hiddenErrorNotification(). Прихований код статусу все одно буде перехоплений filament, але сповіщення не покажеться.

Як альтернативу, ви можете використати метод disabledErrorNotification(), щоб для цього коду статусу повернутися до вбудованої обробки помилок Livewire. Це корисно, якщо ви хочете вклинитися в систему обробки помилок Livewire, щоб налаштувати поведінку для конкретного коду статусу, але для всього іншого лишити систему сповіщень про помилки Filament.

use Filament\Panel;

public function panel(Panel $panel): Panel
{
    return $panel
        // ...
        ->registerErrorNotification(
            title: 'An error occurred',
            body: 'Please try again later.',
        )
        ->hiddenErrorNotification(403)
        ->disabledErrorNotification(503);
}

Також можна вмикати чи вимикати сповіщення про помилки для окремих сторінок панелі, задавши властивість $hasErrorNotifications у класі сторінки:

use Filament\Pages\Dashboard as BaseDashboard;

class Dashboard extends BaseDashboard
{
    protected ?bool $hasErrorNotifications = true;

    // або

    protected ?bool $hasErrorNotifications = false;

    // ...
}

Якщо ви хочете виконати власний код, щоб перевірити, чи слід показувати сповіщення про помилки, скористайтеся методом hasErrorNotifications() у класі сторінки:

use Filament\Pages\Dashboard as BaseDashboard;

class Dashboard extends BaseDashboard
{
    public function hasErrorNotifications(): bool
    {
        return FeatureFlag::active();
    }

    // ...
}

Текст сповіщення про помилку можна зареєструвати й викликом методу registerErrorNotification() у класі сторінки зсередини методу setUpErrorNotifications():

use Filament\Pages\Dashboard as BaseDashboard;

class Dashboard extends BaseDashboard
{
    protected function setUpErrorNotifications(): void
    {
        $this->registerErrorNotification(
            title: 'An error occurred',
            body: 'Please try again later.',
        );
    }

    // ...
}

Так само можна зареєструвати текст сповіщення для конкретного HTTP-статусу, наприклад 404, передавши цей код статусу в параметрі statusCode:

use Filament\Pages\Dashboard as BaseDashboard;

class Dashboard extends BaseDashboard
{
    protected function setUpErrorNotifications(): void
    {
        $this->registerErrorNotification(
            title: 'An error occurred',
            body: 'Please try again later.',
        );

        $this->registerErrorNotification(
            title: 'Record not found',
            body: 'A record you are looking for does not exist.',
            statusCode: 404,
        );
    }

    // ...
}

use Filament\Pages\Dashboard as BaseDashboard;

class Dashboard extends BaseDashboard
{
    protected function setUpErrorNotifications(): void
    {
        $this->registerErrorNotification(
            title: 'An error occurred',
            body: 'Please try again later.',
        );

        $this->hiddenErrorNotification(403);

        $this->disabledErrorNotification(503);
    }

    // ...
}

Оригінал англійською ↗ Глосарій термінів

переклад: Редакція phpukraine · CC-BY-SA-4.0

← ПОПЕРЕДНЯ Початок роботи НАСТУПНА → Навігація

ГОТУЄШСЯ ДО СПІВБЕСІДИ? 4 питання про «Налаштування панелі» на співбесідах · Як працюють middleware і в якому порядку вони виконуються? · Що робить service provider і чим bind відрізняється від singleton і scoped? · Як влаштована авторизація в Laravel: Gates, Policies, middleware, Form Request? · Як працювати з транзакціями в Laravel і коли потрібен lockForUpdate? /interview-questions/laravel→ ХТО НАЙМАЄ Вакансії Laravel в Україні Laravel-вакансії: окремих позицій на Filament ринок не виділяє /jobs/laravel→

Стан перекладу

Перекладаємо з офіційної документації, розділ за розділом, і не ховаємо недоперекладене. Помітили неточність у терміні чи реченні: напишіть, виправимо.

47%

Готовності

У роботі

Ще не перекладено

Глосарій термінів