Создание плагина для панели Filament

• Предисловие
• Обзор
• Шаг 1: Создание плагина
• Шаг 2: Наведение порядка
• Шаг 3: Настройка Provider
• Шаг 4: Создание Widget
• Шаг 5: Обновление Readme

Предисловие

Прежде чем продолжить, ознакомьтесь с документацией по разработке плагинов для панелей Filament и руководством по началу работы c плагинами всё в том же Filament.

Обзор

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

Окончательный код этого плагина находится тут: https://github.com/awcodes/clock-widget.

Шаг 1: Создание плагина.

Сначала создадим плагин, используя шаги, описанные в руководстве по началу работы с плагинами в Filament.

Шаг 2: Наведение порядка.

Далее почистим плагин, чтобы удалить ненужный шаблонный код. Это покажется много, но так как это простой плагин, то можно удалить много ненужного кода.

Удалите следующие каталоги и файлы:

1. config
2. database
3. src/Commands
4. src/Facades
5. stubs

Поскольку наш плагин не содержит никаких настроек или дополнительных методов, необходимых для функциональности, можно также удалить файл ClockWidgetPlugin.php.

• ClockWidgetPlugin.php

Поскольку Filament v3 рекомендует оформлять свои плагины в соответствии с пользовательской темой Filament, вместе с этим будут удалены файлы, необходимые для использования css в плагине. Это необязательно, и при желании можно продолжать использовать css, но это не рекомендуется.

1. resources/css
2. postcss.config.js
3. tailwind.config.js

Теперь можно навести порядок в файле composer.json, чтобы удалить ненужные параметры.

"autoload": {
    "psr-4": {
        // Можно удалить фабрики баз данных
        "Awcodes\\ClockWidget\\Database\\Factories\\": "database/factories/"
    }
},
"extra": {
    "laravel": {
        // Можно удалить фасад
        "aliases": {
            "ClockWidget": "Awcodes\\ClockWidget\\Facades\\ClockWidget"
        }
    }
},

Последний шаг - это обновление файла package.json для удаления ненужных параметров. Замените содержимое файла package.json на следующее:

{
    "private": true,
    "type": "module",
    "scripts": {
        "dev": "node bin/build.js --dev",
        "build": "node bin/build.js"
    },
    "devDependencies": {
        "esbuild": "^0.17.19"
    }
}

После этого нужно установить зависимости:

npm install

Ещё можно удалить директории и файлы Testing, но пока их оставим, хотя в этом примере они не будут использоваться, и вообще рекомендуется писать тесты для своих плагинов.

Шаг 3: Настройка Provider.

Теперь, когда плагин очищен, можно приступать к добавлению кода. В файле src/ClockWidgetServiceProvider.php очень много шаблонов, поэтому давайте удалим все и начнем с нуля.

Важно:
В этом примере будет зарегистрирован асинхронный компонент Alpine. Поскольку эти активы загружаются только по запросу, их можно зарегистрировать как обычно в методе packageBooted(). Если нужно зарегистрировать активы, такие как CSS или JS файлы, которые загружаются на каждой странице, независимо от того, используются они или нет, их следует зарегистрировать в методе register() объекта Plugin конфигурации, используя $panel->assets(). В противном случае, если их зарегистрировать в методе packageBooted(), они будут загружаться в каждой панели, независимо от того, был ли плагин зарегистрирован для этой панели.

Теперь необходимо зарегистрировать наш Widget в панели и загрузить наш компонент Alpine при использовании виджета. Для этого нужно добавить следующий код в метод packageBooted нашего сервис-провайдера. Это зарегистрирует компонент виджета в Livewire и компонент Alpine в Filament Asset Manager.

use Filament\Support\Assets\AlpineComponent;
use Filament\Support\Facades\FilamentAsset;
use Livewire\Livewire;
use Spatie\LaravelPackageTools\Package;
use Spatie\LaravelPackageTools\PackageServiceProvider;
 
class ClockWidgetServiceProvider extends PackageServiceProvider
{
    public static string $name = 'clock-widget';
 
    public function configurePackage(Package $package): void
    {
        $package->name(static::$name)
            ->hasViews()
            ->hasTranslations();
    }
 
    public function packageBooted(): void
    {
        Livewire::component('clock-widget', ClockWidget::class);
 
        // Asset Registration
        FilamentAsset::register(
            assets:[
                 AlpineComponent::make('clock-widget', __DIR__ . '/../resources/dist/clock-widget.js'),
            ],
            package: 'awcodes/clock-widget'
        );
    }
}

Шаг 4: Создание Widget.

Теперь можно создавать наш виджет. Сначала нужно расширить класс Widget Filament в файле ClockWidget.php и указать ему, где найти view для этого виджета. Поскольку для регистрации представлений используется PackageServiceProvider, чтобы указать Filament, где найти представление, используется синтаксис ::.

use Filament\Widgets\Widget;
 
class ClockWidget extends Widget
{
    protected static string $view = 'clock-widget::widget';
}

Далее необходимо создать view для нашего виджета. Создайте новый файл расположенного тут: resources/views/widget.blade.php и добавьте код, приведенный ниже. Чтобы сэкономить время на написание html для виджета, воспользуемся компонентами Blade в Filament.

Для загрузки компонента Alpine используется async Alpine, поэтому нужно добавить атрибут x-ignore в div, который будет загружать наш компонент. Нам также нужно добавить атрибут ax-load к div, чтобы указать Alpine на загрузку нашего компонента. Подробнее об этом вы можете узнать в разделе документации Filament "Основные понятия".

<x-filament-widgets::widget>
    <x-filament::section>
        <x-slot name="heading">
            {{ __('clock-widget::clock-widget.title') }}
        </x-slot>
 
        <div
            x-ignore
            ax-load
            ax-load-src="{{ \Filament\Support\Facades\FilamentAsset::getAlpineComponentSrc('clock-widget', 'awcodes/clock-widget') }}"
            x-data="clockWidget()"
            class="text-center"
        >
            <p>{{ __('clock-widget::clock-widget.description') }}</p>
            <p class="text-xl" x-text="time"></p>
        </div>
    </x-filament::section>
</x-filament-widgets::widget>

Далее необходимо написать наш компонент Alpine в src/js/index.js. И собрать наши активы с помощью npm run build.

export default function clockWidget() {
    return {
        time: new Date().toLocaleTimeString(),
        init() {
            setInterval(() => {
                this.time = new Date().toLocaleTimeString();
            }, 1000);
        }
    }
}

Кроме того, необходимо добавить переводы для текста в виджете, чтобы пользователи могли перевести виджет на свой язык. Переводы будут добавлены в файл resources/lang/en/widget.php.

return [
    'title' => 'Clock Widget',
    'description' => 'Your current time is:',
];

Шаг 5: Обновление Readme.

Ещё стоит обновить файл README.md, включив в него инструкции по установке плагина и любую другую информацию, которой хочется поделиться с пользователями, например, как использовать его в своих проектах. Например:

// Зарегистрируйте плагин и/или виджет в своём провайдере Panel:

use Awcodes\ClockWidget\ClockWidgetWidget;
 
public function panel(Panel $panel): Panel
{
    return $panel
        ->widgets([
            ClockWidgetWidget::class,
        ]);
}

Вот и все, теперь пользователи могут установить наш плагин и использовать его в своих проектах.

Перевод с английского официальной документации Filament:
https://filamentphp.com/docs/3.x/support/plugins/build-a-panel-plugin

Заберите ссылку на статью к себе, чтобы потом легко её найти!
Раз уж досюда дочитали, то может может есть желание рассказать об этом месте своим друзьям, знакомым и просто мимо проходящим?
Не надо себя сдерживать! ;)