Filament v4.5: що нового?

Ми раді повідомити про випуск Filament v4.5!

Сподіваємося, ви добре відпочили під час свят. Хоча в період Різдва та Нового року було тихіше, команда ядра та спільнота продовжували працювати. Ось підсумок наших улюблених новинок із версій v4.4 та v4.5.

# Наші улюблені нові можливості

Нижче — кілька найцікавіших оновлень.

# Rich Editor Mentions

Тепер у Rich Editor можна додавати @mentions. Користувачі вводять тригерний символ (наприклад @ або #), відкривається випадачка пошуку — згадки можна прив’язати до користувачів, задач, тегів або будь‑яких записів, які ви налаштуєте. Обрана згадка вставляється як оформлений inline‑токен.

Щоб увімкнути згадки, використайте метод mentions() з одним або кількома екземплярами MentionProvider:

use Filament\Forms\Components\RichEditor;
use Filament\Forms\Components\RichEditor\MentionProvider;
 
RichEditor::make('content')
    ->mentions([
        MentionProvider::make('@')
            ->items([
                1 => 'Jane Doe',
                2 => 'John Smith',
            ]),
        MentionProvider::make('#')
            ->items([
                'bug' => 'Bug',
                'feature' => 'Feature',
            ]),
    ])

Для великих наборів даних згадки можна підвантажувати динамічно з бази за допомогою getSearchResultsUsing() та getLabelsUsing(). Під час рендерингу ви можете робити згадки посиланнями через метод url() у вашому MentionProvider.

Документація →

# Rich Editor Image Resizing

У Rich Editor зображення тепер можна змінювати за розміром. Коли опція увімкнена, користувачі клікають на зображення і тягнуть маркери зміни розміру; співвідношення сторін зберігається автоматично.

Щоб увімкнути змінення розміру зображень:

use Filament\Forms\Components\RichEditor;
 
RichEditor::make('content')
    ->resizableImages()

# File Upload Aspect Ratio Enforcement

Частий запит — вимагати від зображень певне співвідношення сторін. У v4.5 можна валідувати та примусово застосовувати aspect ratio при завантаженні зображень.

Щоб перевіряти, чи відповідає завантажене зображення потрібному співвідношенню:

use Filament\Forms\Components\FileUpload;
 
FileUpload::make('banner')
    ->image()
    ->imageAspectRatio('16:9')

Можна дозволити кілька співвідношень, передавши масив: ->imageAspectRatio(['16:9', '4:3', '1:1']).

Особливо корисна опція automaticallyOpenImageEditorForAspectRatio(). Якщо користувач завантажив зображення, яке не відповідає потрібному співвідношенню, автоматично відкривається спрощений редактор кадрування, щоб виправити його перед остаточним завантаженням:

use Filament\Forms\Components\FileUpload;
 
FileUpload::make('banner')
    ->image()
    ->imageAspectRatio('16:9')
    ->automaticallyOpenImageEditorForAspectRatio()

Спрощений редактор показує лише область кадрування та кнопки збережити/скасувати, аби швидко привести зображення до потрібного співвідношення. Якщо потрібні повні інструменти редагування, увімкніть обидві опції: imageEditor() і automaticallyOpenImageEditorForAspectRatio().

Документація →

# JavaScript Actions in Schemas

Дії всередині схем (наприклад, у слотах полів форми) тепер можуть виконувати JavaScript прямо в браузері без мережевого запиту. Це зручно для простих взаємодій, наприклад миттєвого оновлення значень полів:

use Filament\Actions\Action;
use Filament\Forms\Components\TextInput;
 
TextInput::make('title')
    ->live(onBlur: true)
    ->afterContent(
        Action::make('generateSlug')
            ->jsAction(<<<'JS'
                $set('slug', $get('title').toLowerCase().replaceAll(' ', '-'))
                JS)
    )
 
TextInput::make('slug')

Рядок JavaScript має доступ до утиліт $get() та $set() для читання і зміни стану полів форми. Оскільки немає мережевого запиту, взаємодія відчувається миттєво.

Зверніть увагу: jsAction() призначений лише для простих клієнтських операцій — він не може підвантажувати вміст модальних вікон або виконувати серверну логіку.

Документація →

# The saved() method

Новий метод saved() — більш зручний і послідовний спосіб не зберігати поле. На відміну від dehydrated(false), він гарантує виключення як прямого значення поля, так і пов’язаних реляцій:

use Filament\Forms\Components\TextInput;
 
TextInput::make('password_confirmation')
    ->password()
    ->saved(false)

Також працює динамічно з замиканнями:

use Filament\Forms\Components\TextInput;
 
TextInput::make('password')
    ->password()
    ->saved(fn (?string $state): bool => filled($state))

# Simpler 2FA Setup with Traits

Налаштування multi‑factor authentication у Filament v4 було вже простим, але вимагало реалізації кількох методів інтерфейсу вручну. У v4.5 додано traits з розумними дефолтами:

use Filament\Auth\MultiFactor\App\Contracts\HasAppAuthentication;
use Filament\Auth\MultiFactor\App\Concerns\InteractsWithAppAuthentication;
use Filament\Auth\MultiFactor\App\Contracts\HasAppAuthenticationRecovery;
use Filament\Auth\MultiFactor\App\Concerns\InteractsWithAppAuthenticationRecovery;
 
class User extends Authenticatable implements FilamentUser, HasAppAuthentication, HasAppAuthenticationRecovery
{
    use InteractsWithAppAuthentication;
    use InteractsWithAppAuthenticationRecovery;
 
    // ...
}

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

Доступні traits:

• InteractsWithAppAuthentication — підтримка authenticator app (OTP)
• InteractsWithAppAuthenticationRecovery — для recovery codes OTP
• InteractsWithEmailAuthentication — для email‑базованої 2FA

Документація →

# Modular Architecture (DDD) Documentation

Для команд, що будують великі застосунки за принципами Domain‑Driven Design, ми додали розгорнуту документацію про інтеграцію Filament з модульними архітектурними пакетами, наприклад InterNACHI/Modular.

У документації розглядається:

• Налаштування модулів з власними Filament‑плагінами
• Умовна реєстрація плагінів для конкретних панелей
• Спільне використання ресурсів між панелями з різними конфігураціями
• Рекомендована структура папок