Filament Shield 中处理 Spatie 翻译字段与权限冲突的解决方案

问题背景

在使用 Filament Shield 和 Spatie 翻译包时，开发人员可能会遇到一个特殊的技术问题：当在 Role 模型中添加可翻译字段（如 description）后，这些字段内容会被错误地保存为新的"自定义权限"并添加到权限表中。这显然不是我们期望的行为。

问题根源分析

这个问题主要由以下几个技术因素共同导致：

1. 模型字段与权限处理的冲突：Filament Shield 默认会收集表单中所有非预设字段（name、guard_name等）作为自定义权限

2. 翻译包的递归处理：Spatie 翻译包会多次调用 mutateFormDataBeforeSave 方法，导致权限收集逻辑被重复执行

3. 字段过滤不完整：原始代码没有考虑到翻译包生成的动态字段名

解决方案实现

基础解决方案

对于简单的非翻译额外字段，可以通过修改 mutateFormDataBeforeSave 方法，明确排除这些字段：

protected function mutateFormDataBeforeSave(array $data): array
{
    $this->permissions = collect($data)
        ->filter(function ($permission, $key) {
            return !in_array($key, ['name', 'guard_name', 'select_all', 'description']);
        })
        ->values()
        ->flatten();
    
    return Arr::only($data, ['name', 'guard_name', 'description', config('permission.column_names.team_foreign_key')]);
}

处理翻译字段的进阶方案

当使用 Spatie 翻译包时，需要更复杂的处理：

1. 添加状态标记：引入一个标志位来区分首次调用和后续调用

protected ?bool $firstMutation = true;

2. 修改处理方法：

protected function mutateFormDataBeforeSave(array $data, $firstMutation = true): array
{
    if($firstMutation) {
        $this->permissions = collect($data)
            ->filter(function ($permission, $key) {
                return !in_array($key, ['name', 'guard_name', 'select_all', 'description']);
            })
            ->values()
            ->flatten();
    }
    return Arr::only($data, ['name', 'guard_name', 'description', config('permission.column_names.team_foreign_key')]);
}

3. 重写翻译包的处理方法：

需要复制 Spatie 包中的 handleRecordUpdate 和 handleRecordCreate 方法，并修改相关调用：

// 修改这一行
$localeData = $this->mutateFormDataBeforeSave($localeData, false);

最佳实践建议

1. 字段命名规范：为可翻译字段使用统一前缀，便于过滤

2. 权限收集优化：在过滤逻辑中添加对翻译字段模式的识别

3. 代码复用：考虑创建一个 Trait 来封装这些修改，便于在多个资源中复用

4. 测试验证：特别要测试多语言场景下的权限收集行为

总结

Filament Shield 与 Spatie 翻译包的集成需要特别注意表单数据处理流程。通过理解两者的交互机制，我们可以有效地解决字段与权限系统的冲突问题。本文提供的解决方案既考虑了基础使用场景，也涵盖了多语言翻译等复杂情况，为开发者提供了完整的技术参考。