# guard

**Repository Path**: zms-code/guard

## Basic Information

- **Project Name**: guard
- **Description**: zms admin权限认证组件
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: hyperf3.2
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-03-15
- **Last Updated**: 2026-07-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# zms/guard — Hyperf 权限认证组件

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

## 安装

```bash
composer require zms/guard
```

发布配置：

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

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

## 配置

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

```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
<?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. 登录 / 登出

```php
use function Zms\Guard\guard;

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

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

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

### 3. 控制器注解鉴权

```php
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（推荐）

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

### Session

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

## 密码工具

```php
use Zms\Guard\Password;

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

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

## License

MIT