Lock LockAware Trait 教程:一行代码让你的 User 对象直接调用 can()

原创2026-11-12 13:20:572,187 阅读
文章标签:软件架构后端

Lock LockAware Trait 教程:一行代码让你的 User 对象直接调用 can()

Lock 是一款面向 PHP 5.4+ 的灵活、基于驱动(driver based)的 ACL 访问控制包。它的 LockAware Trait 让你只需一行 use LockAware,就能让 User、Organization 这类身份对象"自带权限",直接在对象上调用 can()、allow()、deny(),彻底告别每次都从 Manager 里取出 Lock 实例的繁琐写法。

为什么需要 LockAware?

传统方式下,每次校验权限都要走三步:拿到 Manager → 调用 caller($user) 获取 Lock 实例 → 在 Lock 上调用 can():

$lock = $manager->caller($user);
$lock->can('create', 'posts'); // true

问题在于:权限的"所有者"和"使用者"被拆成了两个对象。在控制器、模板里到处传递 $lock 既冗余又容易出错。

LockAware Trait 的思路是:让对象直接持有自己的 Lock 实例,权限检查就长在对象身上:

$user->can('create', 'posts'); // 一行搞定

🎯 这正是 Lock 官方特性列表中的一句话:"Easily implement acl functionality on your caller or role with a trait"。

什么是 LockAware Trait?

Trait 本体位于 src/LockAware.php,它是一个"代理层":内部持有一个私有的 $lock 实例,并把所有公共 API 转发给它。加入这个 Trait 后,你的类立刻获得这些方法:

方法 作用
can() / cannot() 判断是否允许执行某操作
allow() / deny() 授予 / 拒绝权限(可带条件 conditions)
toggle() 翻转某条权限的值
allowed() / denied() 批量获取被允许 / 被拒绝的资源 ID
clear() 清除指定权限
setLock() 绑定该对象自己的 Lock 实例

以 can() 方法 为例,它的实现只有一行核心逻辑:

public function can($action, $resource = null, $resourceId = null)
{
    $this->assertLockInstanceIsSet();
    return $this->lock->can($action, $resource, $resourceId);
}

两个关键的安全机制也写在这个 Trait 里:

  • 未绑定会报错:调用任何 API 前会先执行 assertLockInstanceIsSet(),如果没调用过 setLock(),抛出 LockInstanceNotSet 异常,提示语为 "Please set a valid lock instance on this class before attempting to use it.";
  • 实例必须匹配:setLock() 会校验传入 Lock 实例的 getSubject() 是否就是当前对象,不匹配时抛出 InvalidLockInstance("Invalid Lock instance given for current object."),防止你把 A 用户的锁装到 B 用户身上。

三步让 User 对象直接调用 can()

第 1 步:实现 Caller 契约

每个需要权限的身份对象都要实现 BeatSwitch\Lock\Callers\Caller 契约(见 src/Callers/Caller.php),返回自己的类型、唯一 ID 和角色列表。

第 2 步:引入 LockAware Trait

use BeatSwitch\Lock\Callers\Caller;
use BeatSwitch\Lock\LockAware;

class User implements Caller
{
    use LockAware;

    public function getCallerType() { return 'users'; }
    public function getCallerId()  { return $this->id; }
    public function getCallerRoles() { return ['editor']; }
}

第 3 步:绑定 Lock 实例,直接使用

$lock = $manager->caller($user);
$user->setLock($lock);

$user->can('create', 'posts');  // 权限检查就在对象本身上
$user->allow('edit', 'pages');

官方自带的 SimpleCaller 就是现成的参考实现——它已经 use LockAware,你可以直接拿来用。

更省事的一键方式:makeCallerLockAware

手动"创建 Lock + setLock"两步其实可以由 Manager 一次完成。makeCallerLockAware() 内部先创建对应的 CallerLock 实例,再调用 $caller->setLock($lock),最后把绑好锁的 caller 返回:

$caller = $manager->makeCallerLockAware($caller);

$caller->can('create', 'posts'); // 立即可用

💡 适合在登录引导(bootstrap)阶段调用一次,之后整个请求生命周期内该对象都"权限自知"。

Role 对象同样支持 LockAware

角色(Role)也能享受同样的便利。makeRoleLockAware() 接收角色名或 Role 对象,内部会自动转换为 SimpleRole(该对象已内置 LockAware Trait,见 src/Roles/SimpleRole.php)并绑定 RoleLock:

$role = $manager->makeRoleLockAware('guest');
$role->can('read'); // 直接检查 guest 角色能否 read

配合角色继承(setRole('user', 'guest')),你可以用同样的方式管理整条角色权限链。

常见错误与排查

异常 触发场景 解决方法
LockInstanceNotSet 没调用 setLock() 就使用 can() 等方法 先 setLock(),或改用 $manager->makeCallerLockAware($caller) 一步到位
InvalidLockInstance 传入的 Lock 实例不属于当前对象(getSubject() 不匹配) 确认用的是 $manager->caller($sameObject) 创建出的 Lock
权限始终为 false 检查的 action / resource / resource ID 与 allow() 时设置的不完全一致 权限按"操作 + 资源类型 + 资源 ID"精确匹配,三级都要对上

另外注意:权限实际存储在 Driver 中(如内置的 ArrayDriver),Trait 只是访问入口。条件(conditions)目前仅对静态驱动生效。

相关文件速查

小结

LockAware 是 Lock 包最优雅的设计之一:一行 use LockAware,加一次 setLock()(或直接 makeCallerLockAware),你的 User 对象就能自己回答"我能做什么"。权限检查从"外部工具调用"变成了"对象自身能力",代码更简洁,也更不易出错。🚀

登录后查看全文
lock