跳到主要内容
版本：3.x

从 v2.x 升级

如果你发现本指南中有任何遗落，请发起 PR 到官方仓库！

新的要求​

  • Laravel v10.0+
  • Livewire v3.0+

请在将 Livewire 升级到 v3 前先升级 Filament。如何升级 Livewire 请查看此处。

Livewire v3 最近发布了!
Livewire 团队在使其稳定方面做得很好，不过它是完全重写 Livewire v2。你可能会碰到问题，因此，我们建议在将 Filament v3 使用到生产环境之前对应用进行全面的测试。

自动升级​

升级应用的最简单方式是，运行自动升级脚本。该脚本会自动升级应用到 Filament 的最新版本，并修改你的代码，处理大多数破坏性更新。

composer require filament/upgrade:"^3.2" -W --dev

vendor/bin/filament-v3

请确保仔细按照说明进行操作，并查看脚本所做的更改。之后，你可能需要对代码进行一些手动更改，但脚本应该已经为你处理了大部分重复工作。

此时，创建了一个新文件 app/Providers/Filament/*PanelProvider.php，旧的 config/filament.php 配置文件中的配置项复制过去。由于新配置文件是 Laravel 服务提供者，需要将其注册到 config/app.php 中。Filament 回尝试为你进行注册，不过如果你访问面板出错了，那么可能这一个过程失败了。你可以将其添加到 providers 数组手动注册。

最后，你必须运行 php artisan filament:install 来完成 Filament v3 的安装。所有新的 Filament 项目都必须运行此命令。

然后，你可以运行 composer remove filament/upgrade，因为你不再需要它了。

你所使用的部分插件可能还没有适配 v3。你可以暂时将其移除出 composer.json 文件中，替换成另一个兼容 v3 的类似插件。或者等到插件更新再升级应用，甚至可以发起 PR 帮助作者升级插件。

手动升级​

通过 Composer 升级依赖后，你应该执行 php artisan filament:upgrade 命令，以清理 Laravel 缓存并发布新的前端资源。

高影响更新​

面板提供者替换配置文件​

Filament v2 配置文件变得相当大，现在却非常小。现在，大多数配置都是在服务提供商者完成的，该服务提供者提供了更干净的 API、更安全的类型、IDE 自动补全支持，以及在应用中创建多个面板的能力。我们将这些特殊配置服务提供者称为"面板提供者(panel provider)"。

在创建面板提供者之前，请确保你使用 Composer 安装了 Filament v3。然后，运行以下命令：

php artisan filament:install --panels

新文件 app/Providers/Filament/AdminPanelProvider.php 将被创建，然后就可以将旧的配置从 config/filament.php 文件中转移过去。由于新配置文件是 Laravel 服务提供者，需要将其注册到 config/app.php 中。Filament 回尝试为你进行注册，不过如果你访问面板出错了，那么可能这一个过程失败了。你可以将其添加到 providers 数组手动注册。

大多数配置的转移都是不言自明的，但如果你遇到问题，请参阅配置文档。

最后，运行如下命令将旧的配置文件替换成新配置文件：

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

FILAMENT_FILESYSTEM_DRIVER .env 变量​

FILAMENT_FILESYSTEM_DRIVER .env 环境变量被重命名为 FILAMENT_FILESYSTEM_DISK。这个更新是为了使之与 Laravel 更加一致，因为 Laravel 9 也引入了这一更新。请确保相应地更新 .env 文件，同时别忘记更新生产环境！

资源和关联管理器的引入​

在资源和关系管理器中导入的某些类已移动：

  • Filament\Resources\Form 已移动到 Filament\Forms\Form
  • Filament\Resources\Table 已移动到 Filament\Tables\Table

方法签名变化​

User 模型(实现 FilamentUser 接口)：

  • canAccessFilament() 已被重命名为 canAccessPanel() 并且有了一个新的 \Filament\Panel $panel 参数

资源类：

  • applyGlobalSearchAttributeConstraint() 现在有一个 string $search 参数， 在 $searchAttributes() 之前而非 $searchQuery 之后
  • getGlobalSearchEloquentQuery() 是 public 的
  • getGlobalSearchResults() 有一个 $search 参数替换 $searchQuery
  • getRouteBaseName() 有一个新的 ?string $panel 参数

资源类和所有页面类，包括资源页面、自定义页面、设置页面和仪表盘页面：

  • getActiveNavigationIcon() 是 public
  • getNavigationBadge() 是 public
  • getNavigationBadgeColor() 是 public
  • getNavigationGroup() 是 public
  • getNavigationIcon() 是 public
  • getNavigationLabel() 是 public
  • getNavigationSort() 是 public
  • getNavigationUrl() 是 public
  • shouldRegisterNavigation() 是 public

所有页面类，包括资源页、自定义页、设置页及自定义仪表盘页面：

  • getBreadcrumbs() 为 public
  • getFooterWidgetsColumns() 为 public
  • getHeader() 为 public
  • getHeaderWidgetsColumns() 为 public
  • getHeading() 为 public
  • getRouteName() 有一个新的 ?string $panel 参数
  • getSubheading() 为 public
  • getTitle() 为 public
  • getVisibleFooterWidgets() 为 public
  • getVisibleHeaderWidgets() 为 public

资源列表页及管理页：

  • table() 为 public

资源创建页：

  • canCreateAnother() 为 public

资源编辑及查看页：

  • getFormTabLabel() 现在为 getContentTabLabel()

管理管理器：

  • form() 不再是静态
  • getInverseRelationshipName() 返回值现在为 ?string
  • table() 不再是静态

自定义仪表盘页：

  • getDashboard() 为 public
  • getWidgets() 为 public

属性签名变化​

资源类及所有页面类，包括资源页、自定义页面、设置页及仪表盘页：

  • $middlewares 现在改成 $routeMiddleware

Heroicons 已经升级为 v2​

Heroicons 库已经升级到了 v2。也就是说你应用中使用的任何图标都已经改名了。你可以点击此处查看更新列表。

中等影响更新​

日期时间选择器​

日期时间选择器表单字段现在使用了浏览器默认的本机日期选择器。它通常比旧的日期选择器有更好的用户体验，但你可能会注意到功能缺失、浏览器兼容性差或行为错误。如果要恢复到旧的日期选择器，可以使用 native(false) 方法：

use Filament\Forms\Components\DateTimePicker;

DateTimePicker::make('published_at')
    ->native(false)

Secondary 颜色​

Filament v2 的 secondary 在许多组件中是灰色。所有 secondary 的引用都应该替换成 gray，以保持相同的外观。这一更新释放了 secondary 使之可以注册成你需要的自定义颜色。

$get 和 $set 闭包参数​

表单构造器中，$get 和 $set 参数现在使用了 \Filament\Forms\Get 或 \Filament\Forms\Set 类型，而不再是 \Closure 类型。这使得每个函数的 IDE 自动补全支持更加良好。

快速升级此类代码的一个简单的方法是，查找和替换：

  • Closure $get 替换为 \Filament\Forms\Get $get
  • Closure $set 替换为 \Filament\Forms\Set $set

Blade 图标组件已被禁用​

在 v2 中，我们注意到 Blade 图标组件的性能问题。我们决定在 v3 中默认禁用它，因此，我们只使用 @svg() 语法来渲染图标。

这一变更的副作用是，你所使用的所有自定义图标都必须注册成套。我们不再允许将任意的 Blade 组件用作自定义图标。

Logo 自定义​

在 v2 中，你可以使用 /resources/views/vendor/filament/components/brand.blade.php 文件自定义面板的 Logo。在 v3 中，该功能被移到新增的 brandLogo() API 中。现在你可以在面板配置中设置品牌 Logo。

插件​

Filament v3 有了一个新的通用插件系统，它打破了面板的约束。学习如何创建 v3 插件，点击此处。

低影响变化​

默认 Action 及类型指定的关联管理器类​

如果你在 v2.13 之后开始接触 Filament 项目，可以跳过此部分。从那之后，新的资源和关联管理器已经使用新语法生成。

自 v2.13 起，资源和关联管理器在 table() 方法中定义 Action，而不再是默认的假定操作。

使用简单资源时，请在管理页面中删除 CanCreateRecords、CanDeleteRecords、CanEditRecords 及 CanViewRecords trait。

类型指定管理管理同时被弃用了。任何继承 BelongsToManyRelationManager、HasManyRelationManager、HasManyThroughRelationManager、MorphManyRelationManager 或 MorphToManyRelationManager 的类，现在应该继承 \Filament\Resources\RelationManagers\RelationManager。你也可以从关联管理器中删除 CanAssociateRecords、CanAttachRecords、CanCreateRecords、CanDeleteRecords、CanDetachRecords、CanDisassociateRecords、CanEditRecords 及 CanViewRecords trait。

要了解更多 v2.13 的更新，查阅此博文。

Blade 组件​

有一些 Blade 组件移动到了新的命名空间中：

  • <x-filament::page> 现在改为 <x-filament-panels::page>
  • <x-filament::widget> 现在改为 <x-filament-widgets::widget>

不过，也同时设置了别名，以便你不用修改代码。

没有 $resource 属性的资源页面​

Filament v2 允许不带 $resource 属性创建资源页面。在 v3 中，你必须对其进行声明，否则将出现错误：

Typed static property Filament\Resources\Pages\Page::$resource must not be accessed before initialization

请确保所有的资源页上都设置了 $resource 属性：

protected static string $resource = PostResource::class;