Lock LockAware Trait 教程:一行代码让你的 User 对象直接调用 can()
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 Trait 源码:src/LockAware.php
- Manager 与
makeCallerLockAware/makeRoleLockAware:src/Manager.php - Caller 契约:src/Callers/Caller.php
- CallerLock(校验角色权限的继承逻辑):src/Callers/CallerLock.php
- 内置示例 SimpleCaller:src/Callers/SimpleCaller.php
- 异常定义:LockInstanceNotSet.php、InvalidLockInstance.php
- 完整用法文档:readme.md
小结
LockAware 是 Lock 包最优雅的设计之一:一行 use LockAware,加一次 setLock()(或直接 makeCallerLockAware),你的 User 对象就能自己回答"我能做什么"。权限检查从"外部工具调用"变成了"对象自身能力",代码更简洁,也更不易出错。🚀