Spatie Laravel-Permission 团队权限功能深度解析

赖达笑Gladys

于 2025-06-03 09:05:25 发布

阅读量408

点赞数 5

CC 4.0 BY-SA版权

本文链接：https://blog.youkuaiyun.com/gitblog_00980/article/details/148393035

Spatie Laravel-Permission 团队权限功能深度解析

laravel-permission Associate users with roles and permissions 项目地址: https://gitcode.com/gh_mirrors/la/laravel-permission

团队权限功能概述

Spatie Laravel-Permission 扩展包提供的团队权限功能为多租户系统或团队协作应用提供了灵活的权限控制方案。该功能允许您为不同团队设置独立的角色和权限体系，同时保留全局角色的能力。

功能启用与配置

初始配置

在首次安装包时，必须在执行迁移前完成以下配置：

// config/permission.php
'teams' => true,  // 启用团队功能
'team_foreign_key' => 'team_id' // 可自定义团队外键字段名

已有系统的升级

对于已经运行的系统，升级到团队权限版本需要执行：

运行命令生成迁移文件：php artisan permission:setup-teams
执行数据库迁移：php artisan migrate

核心实现机制

团队中间件设计

团队权限的核心在于正确设置当前活动的 team_id。推荐创建一个专门的中间件来处理：

namespace App\Http\Middleware;

class TeamsPermission
{
    public function handle($request, \Closure $next)
    {
        if(auth()->check()) {
            // 从会话中获取团队ID
            setPermissionsTeamId(session('team_id'));
            
            // API场景下的替代方案示例
            // setPermissionsTeamId(auth('api')->user()->getTeamIdFromToken());
        }
        return $next($request);
    }
}

中间件优先级设置

在 Laravel 中，必须确保团队中间件在 SubstituteBindings 之前执行。对于 Laravel 11.27+，可在 AppServiceProvider 中配置：

public function boot(): void
{
    app()->make(Kernel::class)
        ->addToMiddlewarePriorityBefore(
            SubstituteBindings::class,
            TeamsPermission::class
        );
}

角色与权限管理

角色创建模式

团队环境下有三种角色创建方式：

全局角色：适用于所有团队

Role::create(['name' => 'admin', 'team_id' => null]);

团队专属角色：仅适用于特定团队

Role::create(['name' => 'editor', 'team_id' => 1]);

默认团队角色：使用当前设置的全局 team_id
```
Role::create(['name' => 'viewer']);
```

权限分配机制

权限分配方式与非团队模式相同，但会基于当前设置的 team_id 进行操作：

$user->assignRole('editor');  // 分配当前团队的editor角色
$user->givePermissionTo('edit'); // 授予当前团队的edit权限

团队切换与权限查询

动态团队切换

当需要切换活动团队时，必须遵循以下模式：

// 设置新团队ID
setPermissionsTeamId($newTeamId);

// 清除已加载的关系
$user->unsetRelation('roles')->unsetRelation('permissions');

// 现在可以安全查询
$user->roles; // 获取新团队下的角色
$user->hasRole('manager'); // 检查新团队下的角色

典型应用场景

用户切换团队：在用户界面提供团队选择器
后台管理：查看/编辑不同团队的用户权限
跨团队操作：执行需要多个团队权限的操作

超级管理员实现

在团队环境中实现超级管理员需要特殊处理：

// 在团队模型的创建事件中
self::created(function ($model) {
    $originalTeamId = getPermissionsTeamId();
    setPermissionsTeamId($model->id);
    
    User::find(1) // 超级管理员用户
        ->assignRole('Super Admin');
        
    setPermissionsTeamId($originalTeamId);
});