PHPackages lzpeng/gaara-hyperf - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Authentication & Authorization](/categories/authentication) 4. / 5. lzpeng/gaara-hyperf ActiveLibrary[Authentication & Authorization](/categories/authentication) lzpeng/gaara-hyperf =================== authentication library for hyperf v1.0.0(2mo ago)24951MITPHPPHP >=8.1 Since Jan 5Pushed 1mo ago1 watchersCompare [ Source](https://github.com/liuzhanpeng/gaara-hyperf)[ Packagist](https://packagist.org/packages/lzpeng/gaara-hyperf)[ RSS](/packages/lzpeng-gaara-hyperf/feed)WikiDiscussions master Synced today READMEChangelogDependencies (13)Versions (3)Used By (1) Gaara Hyperf Authentication 使用文档 ================================ [](#gaara-hyperf-authentication-使用文档) [English](README.en.md) 概述 -- [](#概述) `gaara-hyperf` 是一个基于 [Hyperf](https://hyperf.io/) 的认证组件库，整体设计参考 Symfony Security，提供清晰的 Guard、Authenticator 与事件机制, 适用于各种认证场景。 ### 特性 [](#特性) - 表单登录认证 - CSRF 防护 - JSON 登录认证 - 不透明令牌认证 - IP 绑定 / UA 绑定 - 单会话 - API Key 认证 - HMAC 签名认证 - X.509 客户端证书认证 - 内置事件监听器 - IP 白名单监听器 - 登录尝试次数限制监听器 - 密码过期策略监听器 - 审计日志监听器 后续会以扩展库的形式提供更多认证方式： - JWT 认证 [(https://github.com/liuzhanpeng/gaara-hyperf-jwt)](https://github.com/liuzhanpeng/gaara-hyperf-jwt) - 2FA 支持 [(https://github.com/liuzhanpeng/gaara-hyperf-2fa)](https://github.com/liuzhanpeng/gaara-hyperf-2fa) - TOTP 认证 - WebAuthn 认证 [(https://github.com/liuzhanpeng/gaara-hyperf-webauthn)](https://github.com/liuzhanpeng/gaara-hyperf-webauthn) - OAuth 2.0/OpenID Connect - Step-up/Risk-based 认证 --- 安装 -- [](#安装) ``` composer require lzpeng/gaara-hyperf ``` 发布配置文件： ``` php bin/hyperf.php vendor:publish lzpeng/gaara-hyperf ``` 配置文件将发布到 `config/autoload/gaara.php`。 --- 快速开始 ---- [](#快速开始) ### 1. 注册中间件 [](#1-注册中间件) 在 `config/autoload/middlewares.php` 中为需要保护的路由组注册中间件： ``` return [ 'http' => [ \GaaraHyperf\AuthMiddleware::class, ], ]; ``` 也可以在路由定义中直接使用中间件： ``` use GaaraHyperf\AuthMiddleware; Route::get('/profile', function () { // 受保护的路由 })->middleware([AuthMiddleware::class]); ``` ### 2. 配置 Guard [](#2-配置-guard) 推荐先阅读 [5 分钟快速开始](docs/quickstart.md)，再参考 [配置参考](docs/configuration.md) 做扩展。通常你至少需要为一个 Guard 指定： - 请求匹配规则（`matcher`） - 用户提供器（`user_provider`） - 一个或多个认证器（`authenticators`） 示例： ``` return [ 'guards' => [ 'admin' => [ 'matcher' => [ 'pattern' => '^/admin/', 'logout_path' => '/admin/logout', 'exclusions' => ['^/admin/login$'], ], 'user_provider' => [ 'type' => 'model', 'class' => \App\Model\User::class, 'identifier' => 'email', ], 'authenticators' => [ 'form_login' => [ 'check_path' => '/admin/login', 'target_path' => '/admin/dashboard', 'failure_path' => '/admin/login', 'csrf_enabled' => true, 'csrf_id' => 'authenticate', 'csrf_field' => '_csrf_token', ], ], 'token_storage' => [ 'type' => 'session', 'prefix' => 'admin', ], ], ], ]; ``` 你可以按业务场景自由组合认证器、Token 存储、监听器和授权组件。更多场景组合见 [场景化配置](docs/scenarios.md)。 ### 3. 实现用户模型 [](#3-实现用户模型) ``` namespace App\Model; use Hyperf\DbConnection\Model\Model; use GaaraHyperf\User\UserInterface; use GaaraHyperf\User\PasswordAwareUserInterface; class User extends Model implements UserInterface, PasswordAwareUserInterface { public function getIdentifier(): string { return (string) $this->email; } public function getPassword(): string { return $this->password; } } ``` ### 4. 获取当前用户 [](#4-获取当前用户) ``` // 通过辅助函数获取认证上下文 $context = auth(); // 获取当前 Token $token = $context->getToken(); // 获取当前用户对象 $user = $context->getUser(); ``` --- 文档目录 ---- [](#文档目录) - [5 分钟快速开始](docs/quickstart.md) — 复制配置并完成首个可运行认证流程 - [配置参考](docs/configuration.md) — 完整的配置项说明 - [场景化配置](docs/scenarios.md) — 按业务场景选择认证器组合 - [认证器](docs/authenticators.md) — 内置认证器的配置与使用 - [扩展指南](docs/extension.md) — 自定义认证器、用户提供者、监听器等 - [事件系统](docs/events.md) — 事件与监听器详解 - [注意事项](docs/notes.md) — 安全建议与常见问题 ### Health Score 43 — FairBetter than 89% of packages Maintenance89 Actively maintained with recent releases Popularity20 Limited adoption so far Community11 Small or concentrated contributor base Maturity45 Maturing project, gaining track record Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Unknown Total 1 Last Release 79d ago ### Community Maintainers ![](https://avatars.githubusercontent.com/u/6972018?v=4)[lzpeng](/maintainers/liuzhanpeng)[@liuzhanpeng](https://github.com/liuzhanpeng) --- Top Contributors [![liuzhanpeng](https://avatars.githubusercontent.com/u/6972018?v=4)](https://github.com/liuzhanpeng "liuzhanpeng (220 commits)") ### Code Quality TestsPest Code StylePHP CS Fixer ### Embed Badge ![Health badge](/badges/lzpeng-gaara-hyperf/health.svg) ``` [![Health](https://phpackages.com/badges/lzpeng-gaara-hyperf/health.svg)](https://phpackages.com/packages/lzpeng-gaara-hyperf) ``` ### Alternatives [symfony/security-bundle Provides a tight integration of the Security component into the Symfony full-stack framework 2.5k185.6M2.4k](/packages/symfony-security-bundle)[hyperf/hyperf-skeleton A coroutine framework that focuses on hyperspeed and flexible, specifically use for build microservices and middlewares. 313190.9k](/packages/hyperf-hyperf-skeleton)[hyperf/xxl-job-incubator php hyperf xxljob 4837.8k15](/packages/hyperf-xxl-job-incubator) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)