Встановлення · Filament

Filament потребує для роботи:

• PHP 8.2+
• Laravel v11.28+
• Tailwind CSS v4.1+

Встановлення має два варіанти, залежно від того, чи хочете ви будувати застосунок за допомогою конструктора панелей, чи використовувати компоненти всередині Blade-представлень (view) свого застосунку:

Конструктор панелей (Panel builder)

Більшість людей обирає цей варіант, щоб побудувати панель (наприклад, адмін-панель) для свого застосунку. Конструктор панелей обʼєднує всі окремі компоненти в цілісний фреймворк. У межах однієї інсталяції Laravel можна створити скільки завгодно панелей, але встановлювати його потрібно лише раз.

Окремі компоненти (Individual components)

Якщо ви будуєте застосунок з нуля на Blade, можна встановити окремі компоненти Filament, щоб збагатити інтерфейс.

Встановлення конструктора панелей

Встановіть Filament Panel Builder, виконавши такі команди в теці свого Laravel-проєкту:

composer require filament/filament:"^5.0"

php artisan filament:install --panels

Якщо ви встановлюєте Filament через Windows PowerShell, може знадобитися виконати команду нижче, оскільки PowerShell ігнорує символи ^ в обмеженнях версій:

composer require filament/filament:"~5.0"

php artisan filament:install --panels

Це створить і зареєструє новий сервіс-провайдер Laravel з назвою app/Providers/Filament/AdminPanelProvider.php.

Якщо під час доступу до панелі ви отримуєте помилку, перевірте, чи зареєстровано сервіс-провайдер у bootstrap/providers.php. Якщо ні, доведеться додати його вручну.

Створити новий обліковий запис користувача можна такою командою:

php artisan make:filament-user

Відкрийте /admin у браузері, увійдіть і починайте будувати свій застосунок!

Встановлення окремих компонентів

Встановіть потрібні компоненти Filament через Composer:

composer require
    filament/tables:"^5.0"
    filament/schemas:"^5.0"
    filament/forms:"^5.0"
    filament/infolists:"^5.0"
    filament/actions:"^5.0"
    filament/notifications:"^5.0"
    filament/widgets:"^5.0"

Додаткові пакети можна встановити пізніше, не повторюючи ці кроки.

Якщо ви встановлюєте Filament через Windows PowerShell, може знадобитися виконати команду нижче, оскільки PowerShell ігнорує символи ^ в обмеженнях версій:

composer require
    filament/tables:"~5.0"
    filament/schemas:"~5.0"
    filament/forms:"~5.0"
    filament/infolists:"~5.0"
    filament/actions:"~5.0"
    filament/notifications:"~5.0"
    filament/widgets:"~5.0"

Якщо вам потрібен лише набір Blade UI-компонентів, на цьому етапі досить підключити filament/support.

Нові Laravel-проєкти

Швидкий старт із компонентами Filament однією простою командою. Зверніть увагу: вона перезапише змінені файли у вашому застосунку, тому підходить тільки для нових Laravel-проєктів.

Наявні Laravel-проєкти

Якщо у вас уже є Laravel-проєкт, Filament усе одно можна встановити, але робити це слід вручну, щоб зберегти наявну функціональність.

Нові Laravel-проєкти

Щоб швидко налаштувати Filament у новому Laravel-проєкті, виконайте такі команди для встановлення Livewire, Alpine.js і Tailwind CSS:

Ці команди перезапишуть наявні файли у вашому застосунку. Виконуйте їх лише в новому Laravel-проєкті!

Виконайте таку команду, щоб встановити фронтенд-ресурси Filament:

php artisan filament:install --scaffold

npm install

npm run dev

Під час скафолдингу, якщо у вас встановлено пакет Notifications, Filament запитає, чи хочете ви додати потрібний Livewire-компонент у файл стандартного макета. Цей компонент потрібен, якщо ви плануєте надсилати користувачам flash-сповіщення через Filament.

Наявні Laravel-проєкти

Виконайте таку команду, щоб встановити фронтенд-ресурси Filament:

php artisan filament:install

Встановлення Tailwind CSS

Виконайте таку команду, щоб встановити Tailwind CSS і його плагін для Vite, якщо вони ще не встановлені:

npm install tailwindcss @tailwindcss/vite --save-dev

Налаштування стилів

Щоб налаштувати стилі Filament, потрібно імпортувати CSS-файли встановлених пакетів Filament, зазвичай у resources/css/app.css.

Залежно від того, яку комбінацію пакетів ви встановили, можна імпортувати тільки потрібні CSS-файли, щоб CSS-бандл застосунку лишався невеликим:

@import 'tailwindcss';

/* Потрібно для всіх компонентів */
@import '../../vendor/filament/support/resources/css/index.css';

/* Потрібно для дій і таблиць */
@import '../../vendor/filament/actions/resources/css/index.css';

/* Потрібно для дій, форм і таблиць */
@import '../../vendor/filament/forms/resources/css/index.css';

/* Потрібно для дій та інфолістів */
@import '../../vendor/filament/infolists/resources/css/index.css';

/* Потрібно для сповіщень */
@import '../../vendor/filament/notifications/resources/css/index.css';

/* Потрібно для дій, інфолістів, форм, схем і таблиць */
@import '../../vendor/filament/schemas/resources/css/index.css';

/* Потрібно для таблиць */
@import '../../vendor/filament/tables/resources/css/index.css';

/* Потрібно для віджетів */
@import '../../vendor/filament/widgets/resources/css/index.css';

@variant dark (&:where(.dark, .dark *));

Налаштування плагіна Vite

Якщо цього ще не зроблено, додайте плагін @tailwindcss/vite до конфігурації Vite (vite.config.js):

import { defineConfig } from 'vite'
import laravel from 'laravel-vite-plugin'
import tailwindcss from '@tailwindcss/vite'

export default defineConfig({
    plugins: [
        laravel({
            input: ['resources/css/app.css', 'resources/js/app.js'],
            refresh: true,
        }),
        tailwindcss(),
    ],
})

Компіляція ресурсів

Скомпілюйте нові CSS- і JavaScript-ресурси командою npm run dev.

Налаштування макета

Якщо у вас ще немає файлу Blade-макета, створіть його за шляхом resources/views/layouts/app.blade.php такою командою:

php artisan livewire:layout

Додайте до нового файлу макета такий код:

<!DOCTYPE html>
<html lang="{{ str_replace('_', '-', app()->getLocale()) }}">
    <head>
        <meta charset="utf-8">

        <meta name="application-name" content="{{ config('app.name') }}">
        <meta name="csrf-token" content="{{ csrf_token() }}">
        <meta name="viewport" content="width=device-width, initial-scale=1">

        <title>{{ config('app.name') }}</title>

        <style>
            [x-cloak] {
                display: none !important;
            }
        </style>

        @filamentStyles
        @vite('resources/css/app.css')
    </head>

    <body class="antialiased">
        {{ $slot }}

        @livewire('notifications') {{-- Потрібно лише якщо ви хочете надсилати flash-сповіщення --}}

        @filamentScripts
        @vite('resources/js/app.js')
    </body>
</html>

Ключові частини тут: @filamentStyles у <head> макета і @filamentScripts у кінці <body>. Не забудьте також підключити скомпільовані Vite CSS- і JavaScript-файли вашого застосунку!

Рядок @livewire('notifications') потрібен у макеті лише тоді, коли у вас встановлено пакет Notifications і ви хочете надсилати користувачам flash-сповіщення через Filament.

Публікація конфігурації

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

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

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