插件开发 | DevRefinery

引言

Filament 插件的基础是 Laravel 包。它们通过 Composer 安装到你的 Filament 项目中，并遵循所有标准技术，例如使用服务提供者来注册路由、视图和翻译。如果你是 Laravel 包开发的新手，这里有一些资源可以帮助你掌握核心概念：

Laravel 文档的包开发章节可作为一份很棒的参考指南。
Spatie 的软件包开发培训课程是一个很好的教学视频系列，可以一步步地教你整个过程。
Spatie 的包工具允许您使用一个流畅的配置对象来简化您的服务提供者类。

Filament 插件建立在 Laravel 包的概念之上，并允许您为任何 Filament 面板交付和使用可复用功能。它们可以逐个添加到每个面板中，并且也可以为每个面板进行不同的配置。

使用插件类配置面板

一个插件类用于让您的包与面板配置文件进行交互。它是一个简单的PHP类，实现了Plugin接口。需要3个方法：

该 getId() 方法返回该插件在所有插件中的唯一标识符。请确保它足够具体，以免与可能在同一项目中使用的其他插件发生冲突。
该 register() 方法允许您使用面板可用的任何配置选项。这包括注册资源、自定义页面、主题、渲染钩子等。
boot() 方法仅当插件注册到的面板实际使用时才运行。它由一个中间件类执行。

php

<?php

namespace DanHarrin\FilamentBlog;

use DanHarrin\FilamentBlog\Pages\Settings;
use DanHarrin\FilamentBlog\Resources\CategoryResource;
use DanHarrin\FilamentBlog\Resources\PostResource;
use Filament\Contracts\Plugin;
use Filament\Panel;

class BlogPlugin implements Plugin
{
    public function getId(): string
    {
        return 'blog';
    }

    public function register(Panel $panel): void
    {
        $panel
            ->resources([
                PostResource::class,
                CategoryResource::class,
            ])
            ->pages([
                Settings::class,
            ]);
    }

    public function boot(Panel $panel): void
    {
        //
    }
}

您的插件用户可以通过实例化插件类并将其传递给配置的 plugin() 方法，将其添加到面板中：

php

use DanHarrin\FilamentBlog\BlogPlugin;

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

流畅地实例化插件类

你可能希望在你的插件类中添加一个 make() 方法，以提供一个流畅的接口，供你的用户来实例化它。此外，通过使用容器（app()）来实例化插件对象，它可以在运行时被替换为不同的实现：

php

use Filament\Contracts\Plugin;

class BlogPlugin implements Plugin
{
    public static function make(): static
    {
        return app(static::class);
    }
    
    // ...
}

现在，你的用户可以使用 make() 方法：

php

use DanHarrin\FilamentBlog\BlogPlugin;
use Filament\Panel;

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

按面板配置插件

您可以向您的插件类中添加其他方法，以便用户配置它。我们建议您为您提供的每个选项都添加一个设置器方法和一个获取器方法。您应该使用一个属性在设置器中存储偏好设置，并在获取器中再次检索它：

php

use DanHarrin\FilamentBlog\Resources\AuthorResource;
use Filament\Contracts\Plugin;
use Filament\Panel;

class BlogPlugin implements Plugin
{
    protected bool $hasAuthorResource = false;
    
    public function authorResource(bool $condition = true): static
    {
        // This is the setter method, where the user's preference is
        // stored in a property on the plugin object.
        $this->hasAuthorResource = $condition;
    
        // The plugin object is returned from the setter method to
        // allow fluent chaining of configuration options.
        return $this;
    }
    
    public function hasAuthorResource(): bool
    {
        // This is the getter method, where the user's preference
        // is retrieved from the plugin property.
        return $this->hasAuthorResource;
    }
    
    public function register(Panel $panel): void
    {
        // Since the `register()` method is executed after the user
        // configures the plugin, you can access any of their
        // preferences inside it.
        if ($this->hasAuthorResource()) {
            // Here, we only register the author resource on the
            // panel if the user has requested it.
            $panel->resources([
                AuthorResource::class,
            ]);
        }
    }
    
    // ...
}

此外，您可以使用插件的唯一 ID 从插件类外部访问其任何配置选项。为此，将 ID 传递给 filament() 方法：

php

filament('blog')->hasAuthorResource()

您可能希望在访问配置时拥有更好的类型安全和 IDE 自动补全。如何实现这一点完全取决于您，但一个想法是向插件类添加一个静态方法来检索它：

php

use Filament\Contracts\Plugin;

class BlogPlugin implements Plugin
{
    public static function get(): static
    {
        return filament(app(static::class)->getId());
    }
    
    // ...
}

现在, 你可以使用新的静态方法访问插件配置:

php

BlogPlugin::get()->hasAuthorResource()

在插件中分发面板

在 Laravel 包中分发一个完整的面板非常容易。这样，用户只需安装你的插件，就能获得一个预构建的全新应用部分。

当配置面板时，配置类继承 PanelProvider 类，并且它是一个标准的 Laravel 服务提供者。您可以在您的包中将其用作服务提供者：

php

<?php

namespace DanHarrin\FilamentBlog;

use Filament\Panel;
use Filament\PanelProvider;

class BlogPanelProvider extends PanelProvider
{
    public function panel(Panel $panel): Panel
    {
        return $panel
            ->id('blog')
            ->path('blog')
            ->resources([
                // ...
            ])
            ->pages([
                // ...
            ])
            ->widgets([
                // ...
            ])
            ->middleware([
                // ...
            ])
            ->authMiddleware([
                // ...
            ]);
    }
}

然后你应在你的包的 composer.json 中将其注册为服务提供者：

json

"extra": {
    "laravel": {
        "providers": [
            "DanHarrin\\FilamentBlog\\BlogPanelProvider"
        ]
    }
}

引言

Laravel 文档的包开发章节可作为一份很棒的参考指南。
Spatie 的软件包开发培训课程是一个很好的教学视频系列，可以一步步地教你整个过程。
Spatie 的包工具允许您使用一个流畅的配置对象来简化您的服务提供者类。

使用插件类配置面板

一个插件类用于让您的包与面板配置文件进行交互。它是一个简单的PHP类，实现了Plugin接口。需要3个方法：

该 getId() 方法返回该插件在所有插件中的唯一标识符。请确保它足够具体，以免与可能在同一项目中使用的其他插件发生冲突。
该 register() 方法允许您使用面板可用的任何配置选项。这包括注册资源、自定义页面、主题、渲染钩子等。
boot() 方法仅当插件注册到的面板实际使用时才运行。它由一个中间件类执行。

php

<?php

namespace DanHarrin\FilamentBlog;

use DanHarrin\FilamentBlog\Pages\Settings;
use DanHarrin\FilamentBlog\Resources\CategoryResource;
use DanHarrin\FilamentBlog\Resources\PostResource;
use Filament\Contracts\Plugin;
use Filament\Panel;

class BlogPlugin implements Plugin
{
    public function getId(): string
    {
        return 'blog';
    }

    public function register(Panel $panel): void
    {
        $panel
            ->resources([
                PostResource::class,
                CategoryResource::class,
            ])
            ->pages([
                Settings::class,
            ]);
    }

    public function boot(Panel $panel): void
    {
        //
    }
}

您的插件用户可以通过实例化插件类并将其传递给配置的 plugin() 方法，将其添加到面板中：

php

use DanHarrin\FilamentBlog\BlogPlugin;

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

流畅地实例化插件类

php

use Filament\Contracts\Plugin;

class BlogPlugin implements Plugin
{
    public static function make(): static
    {
        return app(static::class);
    }
    
    // ...
}

现在，你的用户可以使用 make() 方法：

php

use DanHarrin\FilamentBlog\BlogPlugin;
use Filament\Panel;

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

按面板配置插件

php

use DanHarrin\FilamentBlog\Resources\AuthorResource;
use Filament\Contracts\Plugin;
use Filament\Panel;

class BlogPlugin implements Plugin
{
    protected bool $hasAuthorResource = false;
    
    public function authorResource(bool $condition = true): static
    {
        // This is the setter method, where the user's preference is
        // stored in a property on the plugin object.
        $this->hasAuthorResource = $condition;
    
        // The plugin object is returned from the setter method to
        // allow fluent chaining of configuration options.
        return $this;
    }
    
    public function hasAuthorResource(): bool
    {
        // This is the getter method, where the user's preference
        // is retrieved from the plugin property.
        return $this->hasAuthorResource;
    }
    
    public function register(Panel $panel): void
    {
        // Since the `register()` method is executed after the user
        // configures the plugin, you can access any of their
        // preferences inside it.
        if ($this->hasAuthorResource()) {
            // Here, we only register the author resource on the
            // panel if the user has requested it.
            $panel->resources([
                AuthorResource::class,
            ]);
        }
    }
    
    // ...
}

此外，您可以使用插件的唯一 ID 从插件类外部访问其任何配置选项。为此，将 ID 传递给 filament() 方法：

php

filament('blog')->hasAuthorResource()

您可能希望在访问配置时拥有更好的类型安全和 IDE 自动补全。如何实现这一点完全取决于您，但一个想法是向插件类添加一个静态方法来检索它：

php

use Filament\Contracts\Plugin;

class BlogPlugin implements Plugin
{
    public static function get(): static
    {
        return filament(app(static::class)->getId());
    }
    
    // ...
}

现在, 你可以使用新的静态方法访问插件配置:

php

BlogPlugin::get()->hasAuthorResource()

在插件中分发面板

在 Laravel 包中分发一个完整的面板非常容易。这样，用户只需安装你的插件，就能获得一个预构建的全新应用部分。

当配置面板时，配置类继承 PanelProvider 类，并且它是一个标准的 Laravel 服务提供者。您可以在您的包中将其用作服务提供者：

php

<?php

namespace DanHarrin\FilamentBlog;

use Filament\Panel;
use Filament\PanelProvider;

class BlogPanelProvider extends PanelProvider
{
    public function panel(Panel $panel): Panel
    {
        return $panel
            ->id('blog')
            ->path('blog')
            ->resources([
                // ...
            ])
            ->pages([
                // ...
            ])
            ->widgets([
                // ...
            ])
            ->middleware([
                // ...
            ])
            ->authMiddleware([
                // ...
            ]);
    }
}

然后你应在你的包的 composer.json 中将其注册为服务提供者：

json

"extra": {
    "laravel": {
        "providers": [
            "DanHarrin\\FilamentBlog\\BlogPanelProvider"
        ]
    }
}

文档导航

引言

使用插件类配置面板

流畅地实例化插件类

按面板配置插件

在插件中分发面板

引言

使用插件类配置面板

流畅地实例化插件类

按面板配置插件

在插件中分发面板