filament-pro

Filament v5

使用 Filament v5 基于 Schema 和 Livewire v4 响应性的服务端驱动 UI，构建功能强大的 Laravel 管理面板。

概述

Filament v5 是一个 Laravel 管理面板框架，通过声明式 PHP API 提供完整的 CRUD 界面、表单、表格和仪表板组件。它基于 Livewire v4 构建，无需编写 JavaScript 即可实现实时响应。

核心概念

• PanelProvider：用于定义管理面板的中央配置类
• 资源：为 Eloquent 模型提供自动生成的 CRUD 界面
• Schema：声明式 UI 组件（表单、表格、信息列表）
• 操作：带有模态框和后端逻辑的交互式按钮
• 小组件：用于数据可视化的仪表板组件

系统要求

• Laravel 11.28+
• PHP 8.2+
• Livewire v4
• Node.js 18+
• Tailwind CSS v4.1+

安装

通过 Composer 安装 Filament 并搭建面板：

composer require filament/filament:"^5.0" -W
php artisan filament:install --scaffold
npm install && npm run dev
php artisan make:filament-user

这会创建面板提供者、目录结构和所需资源，供你开始构建。

目录结构

app/
  Filament/
    Resources/          # CRUD resources with forms and tables
    Pages/              # Custom pages
    Widgets/            # Dashboard widgets
  Providers/
    Filament/
      AdminPanelProvider.php

核心概念

面板配置

PanelProvider 是管理面板的入口。它负责配置：

• 身份信息：ID、路径、品牌信息（名称、徽标、颜色）
• 发现：自动发现资源、页面和小组件
• 中间件：会话、身份验证和自定义中间件
• 多租户：为 SaaS 应用配置多租户

资源

资源通过以下功能提供完整的 CRUD 界面：

• 表单：基于 Schema 的表单，包含 20 多种字段类型（TextInput、Select、DatePicker、FileUpload、RichEditor 等）
• 表格：包含列、筛选器、排序和操作的数据表格
• 页面：自动生成列表、创建、编辑和查看页面
• 关系：用于处理模型关系的关系管理器

表单

表单采用基于 Schema 的方式，你可以将字段声明为 PHP 对象：

• 输入字段：文本、选择框、复选框、切换开关、日期/时间选择器
• 媒体：带验证的文件和图片上传
• 复杂字段：富文本编辑器、重复器、构建器
• 布局：网格、分区、选项卡和向导
• 验证：内置 Laravel 验证规则

表格

表格支持丰富的自定义选项，用于显示数据：

• 列：文本、徽标、图标、图片、颜色
• 筛选器：选择、三态和自定义筛选逻辑
• 操作：行级操作、批量操作、表头操作
• 功能：搜索、排序、分页、分组

操作

操作是可触发以下功能的交互式按钮：

• 模态框：用于收集数据的表单对话框
• 确认：确认破坏性操作
• 向导：多步骤流程
• 通知：操作完成后的用户反馈

小组件

仪表板小组件包括：

• 统计概览：带有趋势和迷你图的指标卡片
• 图表：使用 Chart.js 绘制折线图、柱状图和饼图
• 表格：用于显示最近记录的数据表格

测试

Filament 使用 Pest PHP 和 Livewire 测试辅助工具：

• 页面测试：列表、创建、编辑和查看页面功能
• 表单测试：验证、状态管理、提交
• 表格测试：搜索、筛选器、排序、操作
• 授权测试：访问控制和权限

授权

通过以下方式实现访问控制：

• 面板访问：使用 FilamentUser 契约控制面板级访问
• 策略：使用 Laravel 策略管理资源级权限
• 字段可见性：根据用户角色显示或隐藏字段
• 多租户：为 SaaS 应用隔离租户数据

架构模式

服务端驱动 UI

Filament 采用服务端驱动的方式，由后端通过 Schema 定义 UI 结构。PHP 代码描述表单、表格和布局，Filament 则将其渲染为 Livewire 组件。

Schema 系统

Schema 是定义以下内容的 PHP 配置对象：

• 表单字段及其验证规则
• 表格列及其格式
• 布局容器（网格、分区、选项卡）
• 操作定义及其行为

Livewire 集成

所有组件都会挂载为 Livewire 组件，提供以下功能：

• 无需重新加载页面即可实时响应
• 自动管理状态
• 处理事件并通过 AJAX 更新
• 表单验证并即时反馈

资源优先设计

该框架鼓励采用资源优先的方法：

1. 定义 Eloquent 模型
2. 创建与这些模型对应的资源
3. 为每个资源配置表单和表格
4. 根据需要添加操作和小组件

命令参考

命令	用途
filament:install --scaffold	安装 Filament 并搭建面板脚手架
make:filament-resource	创建 CRUD 资源
make:filament-page	创建自定义页面
make:filament-widget	创建仪表板小组件
make:filament-panel	创建其他面板
make:filament-user	创建管理员用户
make:filament-relation-manager	创建关系管理器
filament:cache-components	缓存组件以用于生产环境

详细文档

参考指南

各组件的完整文档：

• 表单 - 所有表单组件、验证规则、布局和条件逻辑
• 表格 - 列类型、筛选器、操作和表格配置
• 资源 - CRUD 资源、关系管理器、信息列表和全局搜索
• 信息列表 - 只读数据展示组件（TextEntry、ImageEntry、IconEntry）
• 小组件 - 统计概览、图表和表格小组件
• 操作 - 模态操作、通知、操作组和向导
• 通知 - 闪现消息、数据库通知和广播通知
• 架构 - 架构系统、布局和组件组织
• 测试 - 针对资源、表单、表格和授权的 Pest 测试模式
• 授权 - 访问控制、策略、角色和多租户

代码示例

请参阅 examples.md，其中包含完整且可运行的代码示例，包括：

• 完整的资源实现
• 表单配置
• 表格设置
• 小组件配置
• 测试套件
• 授权模式

最佳实践

性能

• 使用 getEloquentQuery() 预加载关联，防止出现 N+1 查询
• 在生产环境中使用 filament:cache-components 启用组件缓存
• 限制分页选项，并对大型数据集使用延迟加载
• 缓存小组件中的高开销计算

安全

• 始终实现 FilamentUser 契约以控制面板访问权限
• 使用 Laravel 策略进行资源级授权
• 使用适当的表单规则验证所有输入
• 在生产环境中绝不跳过授权
• 为多租户应用实现适当的租户隔离

代码组织

• 按功能组织：app/Filament/Admin/Resources/
• 将复杂表单和表格提取到单独的类中
• 为常见模式创建可复用的表单组件
• 让资源专注于单一职责
• 为非 CRUD 功能使用专用页面

测试

• 测试每个资源的所有 CRUD 操作
• 在多种场景下验证表单验证规则
• 测试表格功能：搜索、筛选、排序和操作
• 使用不同用户角色验证授权
• 使用工厂创建真实的测试数据

何时使用 Filament

Filament 非常适合用于：

• 管理面板：用于管理应用数据的后台界面
• CMS：具备丰富编辑功能的内容管理系统
• CRM：客户关系管理工具
• 电子商务：产品、订单和库存管理
• SaaS 应用：多租户管理界面
• 内部工具：业务流程管理和数据录入

Additional Resources

• Official Documentation
• GitHub Repository
• Live Demo
• Discord Community

---

Version: 1.0.0
License: MIT
Compatibility: Laravel 11+, PHP 8.2+, Livewire v4