zms/guard

zms后台管理系统权限认证组件，基于AOP注解驱动

v3.3.0 2026-07-22 06:28 UTC

Requires

• php: >=8.2
• ext-redis: *
• hyperf/config: ^3.1
• hyperf/context: ^3.1
• hyperf/contract: ^3.1
• hyperf/db-connection: ^3.1
• hyperf/di: ^3.2
• hyperf/http-server: ^3.1
• hyperf/redis: ^3.2
• hyperf/server: ^3.1
• hyperf/support: ^3.1
• psr/container: ^2.0
• psr/event-dispatcher: ^1.0
• zms/admin-helper: ^3.2
• zms/exception: ^1.0
• zms/unit: ^1.0

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3.0
• jetbrains/phpstorm-attributes: ^1.0
• phpstan/phpstan: ^1.0
• phpunit/phpunit: ^10.0

Suggests

• hyperf/event-dispatcher: Required if using the logger event feature.
• swow/swow: Required to create swow components.

MIT

• php
• auth
• rbac
• guard
• hyperf

Published on Packagist.org on 2026-07-22 06:30 UTC

README

基于 AOP 注解的权限认证组件，支持多用户组、Redis/Session 存储、权限节点自动收集。

安装

composer require zms/guard

发布配置：

php bin/hyperf.php vendor:publish zms/guard

会在 config/autoload/guard.php 生成配置文件。

配置

在 config/autoload/guard.php 中配置用户组：

<?php
use Zms\Guard\Config;
use Zms\Guard\Drivers\RedisDrivers;

return [
    'admin' => new Config(
        key:        'admin_token',         // 缓存 key 前缀
        drive:      RedisDrivers::class,   // 存储驱动
        ttl:        3600 * 24 * 7,         // 登录有效期（秒）
        secret:     Config::SECRET_SECRET, // 凭证来源：header|query|post|session
        secret_key: 'Authorization',       // Header 名 / 参数名
        guard:      function (int $userId) {
            return \App\Model\Admin::find($userId);
        }
    ),
];

Config 参数说明

参数	类型	默认值	说明
key	string	—	缓存 key 前缀（必填）
drive	string	—	存储驱动类名（必填）
ttl	int	2592000 (30天)	登录有效期（秒）
secret	string	'header'	凭证来源：SECRET_SECRET/SECRET_QUERY/SECRET_POST/SECRET_SESSION
secret_key	string	'Authorization'	Header 名 / Query 参数名 / Post 参数名
guard	\Closure	null	用户模型查询回调 fn(int $id): ModelInterface

使用

1. 实现用户模型

实现 ModelInterface 接口：

<?php
namespace App\Model;

use Zms\Guard\ModelInterface;
use Hyperf\DbConnection\Model\Model;

class Admin extends Model implements ModelInterface
{
    public function getId(): int|string
    {
        return $this->id;
    }

    public function userInfo(): array
    {
        return ['id' => $this->id, 'name' => $this->name];
    }

    public function generatePassword(string $password, string $secretKey = ''): string
    {
        return \Zms\Guard\Password::hash($password);
    }

    public function generateSecretKey(): string
    {
        return bin2hex(random_bytes(32));
    }

    public function verifyPassword(string $password, string $passwordHas, string $secretKey = ''): bool
    {
        return \Zms\Guard\Password::verify($password, $passwordHas);
    }

    public function authorize(mixed $auth): bool
    {
        // $auth 是 #[Auth] 注解的配置数组
        // 返回 true 表示有权限，false 表示无权限
        return true;
    }
}

2. 登录 / 登出

use function Zms\Guard\guard;

// 登录
$guard = guard('admin');
$token = $guard->login($userId);

// 获取当前登录用户
$user = $guard->user();
$uid  = $guard->uid();

// 登出
$guard->logout();

3. 控制器注解鉴权

use Zms\Guard\Auth;

class UserController
{
    // 需要登录 + 验证权限
    #[Auth(guard: 'admin', sign: 'user.create', label: ['用户管理', '添加用户'])]
    public function create()
    {
        // ...
    }

    // 允许游客访问
    #[Auth(guard: 'admin', tourist: true)]
    public publicList()
    {
        // ...
    }

    // 跳过权限检查
    #[Auth(guard: 'admin', sign: 'skip')]
    public profile()
    {
        // ...
    }

    // 依赖其他权限
    #[Auth(guard: 'admin', sign: 'user.delete', relyon: ['user.list'], label: ['用户管理', '删除用户'])]
    public function delete()
    {
        // ...
    }

    // 记录日志（GET/POST）
    #[Auth(guard: 'admin', sign: 'user.update', logger: 'POST', label: ['用户管理', '修改用户'])]
    public function update()
    {
        // ...
    }
}

4. Auth 注解参数

参数	类型	默认值	说明
guard	?string	null	所属用户组名
sign	?string	null	权限标识，'skip' 表示跳过权限检查
label	?array	[]	权限标签 [分类, 操作]
tourist	bool	false	是否允许游客访问
relyon	?array	null	依赖的其他权限
prefix	?string	null	权限前缀
mode	?array	null	允许的环境 ['dev', 'prod'] 或 ['*']
logger	mixed	true	日志记录：true(所有) / 'GET' / 'POST' / false
record	array	[]	记录的参数字段
check	bool	true	是否检查权限
describe	?string	null	操作描述
app	?string	null	所属应用
view	?string	null	视图路径
process	?bool	null	是否记录进程
remove	bool	false	是否移除

存储驱动

Redis（推荐）

use Zms\Guard\Drivers\RedisDrivers;
// drive => RedisDrivers::class

Session

use Zms\Guard\Drivers\SessionDrivers;
// drive => SessionDrivers::class

密码工具

use Zms\Guard\Password;

// 生成哈希
$hash = Password::hash('mypassword');

// 验证
if (Password::verify('mypassword', $hash)) {
    // 密码正确
}

License

MIT