适配 Yii 3.0，php-casbin/yii-permission 3.0 正式发布

Ada

发布时间：2026-08-25| 151人浏览过

原创

前言

在 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-permission 3.0 对 Yii 3.0 生态的适配重点 — **0 版适配重点一览**这张配图适合放在版本背景章节后，帮助读者快速看清 3.0 与 Yii 3.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 应用里，中间件已经成为更通用也更易复用的组织方式。

以请求流转便签图说明 EnforcerMiddleware 与 RequestMiddleware 在权限链路中的位置 — **权限拦截进入请求管道**这张图放在中间件章节后更合适，突出权限校验从传统组件迁移到请求管道后的变化。

yii-permission 3.0 这次把权限处理核心放进了基于 PSR-15 的 HTTP 中间件体系中，主要包括两个部分：

EnforcerMiddleware：在请求处理管道中直接执行基于 Casbin 模型的权限决策与拦截。
RequestMiddleware：负责对传入请求做上下文预处理和信息提取，便于后续权限判断使用。

这种调整带来的实际意义很直接。首先，权限逻辑可以更自然地挂到全局请求管道，或者挂到某一组路由上，不再强绑定控制器实现。其次，中间件模式在现代 PHP 框架与组件间的复用性更高，后续维护和组合也更清晰。对于需要按模块、按接口组甚至按租户策略组织访问控制的项目，这种结构会更容易扩展。

如果把它理解成一次“权限系统位置前移”，也基本没问题：权限校验不再只是控制器里的附属动作，而是成为 HTTP 请求生命周期中的标准一环。

Yii 原生调用习惯还能保留吗

这是很多 Yii 开发者在看权限扩展升级时最关心的问题。yii-permission 3.0 给出的答案是：尽量保留原生开发体验。

通过对照卡片展示 AccessChecker 如何把 Casbin 决策接到 Yii 原生 can 调用上 — **从 can() 到 Casbin 的衔接方式**这张图适合放在访问检查接口章节后，帮助读者理解“底层换了、调用习惯尽量不变”这一点。

新版本新增了实现 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 版本测试矩阵以及代码覆盖率配置。