在 Yii 3.0 逐步转向独立组件和 PSR 规范后，权限控制扩展也必须跟着底层架构一起调整。php-casbin/yii-permission 3.0 这次发布，核心不是简单追版本号，而是把 Casbin 在 Yii 生态中的接入方式整体换成更符合新框架设计的做法。对准备上 Yii 3.0 的团队来说，判断它值不值得用，主要就看三点：运行环境是否匹配、权限拦截是否足够现代、以及业务代码能否平滑延续原有的访问检查习惯。
为什么说 3.0 是一次面向 Yii 3.0 的重构
php-casbin/yii-permission 是 Casbin 在 PHP Yii 框架生态中的官方扩展。根据发布信息，该项目已于 2026 年 7 月 30 日 正式推出 v3.0.0。
这一版最关键的变化，是完整转向 Yii 3.0 的独立组件生态。Yii 3.0 相比旧版本，更强调组件化、标准化和基于 PSR 的协作方式，因此 yii-permission 也不再沿用早期框架里那种偏传统的挂载模式，而是从接口集成、依赖注入到请求处理链都做了相应调整。
同时，版本升级也带来了明确的环境门槛：
- 最低运行环境提升到 PHP 8.2+。
- 面向 Yii 3.0 框架包与其独立组件体系。
- 配置方式转向
yiisoft/config，用于统一管理依赖注入容器配置。
这意味着它更适合新项目，或者已经明确要往 Yii 3 组件化架构迁移的项目。如果还停留在旧版 Yii 2.x 的既有结构里，那么 3.0 的升级价值很高，但迁移动作也不会是“直接替换包版本”这么简单。
权限拦截方式变了：从传统组件转向 PSR-15 中间件
在 Yii 2.0 时代，权限控制通常依赖控制器级别的 Behavior，或者通过 Application 组件来完成请求拦截。这种做法在旧架构下没有问题，但在现代 PHP Web 应用里，中间件已经成为更通用也更易复用的组织方式。
yii-permission 3.0 这次把权限处理核心放进了基于 PSR-15 的 HTTP 中间件体系中，主要包括两个部分：
EnforcerMiddleware：在请求处理管道中直接执行基于 Casbin 模型的权限决策与拦截。RequestMiddleware：负责对传入请求做上下文预处理和信息提取，便于后续权限判断使用。
这种调整带来的实际意义很直接。首先，权限逻辑可以更自然地挂到全局请求管道，或者挂到某一组路由上，不再强绑定控制器实现。其次，中间件模式在现代 PHP 框架与组件间的复用性更高，后续维护和组合也更清晰。对于需要按模块、按接口组甚至按租户策略组织访问控制的项目，这种结构会更容易扩展。
如果把它理解成一次“权限系统位置前移”，也基本没问题：权限校验不再只是控制器里的附属动作，而是成为 HTTP 请求生命周期中的标准一环。
Yii 原生调用习惯还能保留吗
这是很多 Yii 开发者在看权限扩展升级时最关心的问题。yii-permission 3.0 给出的答案是：尽量保留原生开发体验。
新版本新增了实现 YiisoftAccessAccessCheckerInterface 接口的 AccessChecker 类，用来对接 Yii 常见的访问检查语义。这样做的好处在于，底层虽然已经改成 Casbin 决策引擎驱动，但在应用层，开发者仍可以继续沿用熟悉的调用方式。
// 借助统一接口，在控制器或服务层轻松完成权限检查
if ($user->can('article.update', ['article' => $article])) {
// 允许执行更新操作
}这段调用方式的意义不只是“写起来顺手”。更重要的是，它降低了项目迁移时的改造范围：控制器、服务层甚至部分既有授权判断代码，不一定要因为底层权限引擎换成 Casbin 就整体重写。对于已经依赖 Yii 原生访问检查语义的团队，这一点会直接影响接入成本。
这次发布具体更新了什么
结合官方发布日志，v3.0.0 的核心更新点可以归纳为以下几项：
- 适配 Yii 3.0 框架：完整支持 Yii 3.0 的独立组件生态与依赖注入规范。
- 升级环境要求：运行环境要求为 PHP 8.2 及以上，并面向 Yii 3.0 框架包使用。
- 引入 PSR-15 中间件架构：通过
EnforcerMiddleware和RequestMiddleware替代旧版依赖传统控制器组件的做法。 - 新增原生 AccessChecker 支持：提供
AccessChecker，实现YiisoftAccessAccessCheckerInterface，可无缝衔接$user->can()。 - 配置与工程化同步升级：使用
yiisoft/config统一管理 DI 配置，并同步更新 GitHub Actions CI 工作流、PHP 版本测试矩阵以及代码覆盖率配置。
从这些变化可以看出，3.0 不只是加了几个新类，而是把运行时接入、开发接口和工程配置一起拉到了 Yii 3.0 时代的标准上。
哪些项目适合升级，怎么判断值不值得上
如果你的项目符合下面这些条件，那么 php-casbin/yii-permission 3.0 基本可以优先纳入评估：
- 正在使用或计划采用 PHP 8.2+。
- 新项目直接基于 Yii 3.0 组件生态构建。
- 希望把访问控制放进标准中间件链，而不是继续依赖旧式控制器挂载方式。
- 既需要 Casbin 的 ACL、RBAC、ABAC 等模型能力，又希望保留 Yii 侧较熟悉的访问检查接口。
对这类项目来说，它的优势很明确：既能覆盖单租户场景下的简单 RBAC，也能支撑多租户、带属性条件的 ABAC 权限判断，并且整体接入方式更干净、更标准化。
但如果现有系统仍深度绑定 Yii 2.x 风格的控制器行为、组件注册和旧权限链路，那么升级时就应该把它视为一次架构迁移工作，而不是普通的小版本替换。重点要评估的是中间件接入方式、DI 配置迁移以及业务侧授权调用的兼容范围。
总体来看，php-casbin/yii-permission 3.0 的发布，意味着 Casbin 在 Yii 生态中的官方权限方案，已经正式切换到面向 Yii 3.0 的现代接入形态。对新项目，它是一个更顺手的默认选项；对升级项目，则更适合作为一次有计划的权限层重构来推进。
项目仓库可在 GitHub 搜索查看：php-casbin/yii-permission。
