PHP-Casbin 是什么：一套支持 ACL、RBAC、ABAC 的 PHP 权限框架怎么用

Aria

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

原创

前言

在 PHP 项目里，权限逻辑一旦分散到控制器、服务层和各类判断分支里，后期通常会越来越难维护。PHP-Casbin 试图把这件事单独抽出来：它不负责登录认证，也不接管用户管理，而是专注于“谁能对什么资源执行什么操作”的访问控制，并通过统一模型与策略来组织规则。读完这篇，你可以快速判断它是否适合自己的项目，以及最基本的接入方式该怎么落地。

PHP-Casbin 能解决什么问题

PHP-Casbin 是一个用 PHP 编写的轻量级开源访问控制框架，项目地址为 https://github.com/php-casbin/php-casbin。它采用元模型设计，重点不是把权限写死成某一种方案，而是通过统一抽象去支持多种经典访问控制模型。

用纸面卡片方式展示 PHP-Casbin 的核心组成，包括请求格式、模型、策略和路径匹配能力。 — **PHP-Casbin 的权限引擎结构**把 PHP-Casbin 看成“请求进入、模型判定、策略落地”的授权引擎。

从能力范围看，PHP-Casbin 可以覆盖 ACL、RBAC、ABAC 等常见权限模型。对于需要同时管理用户、角色、资源、动作这些维度的业务系统来说，这种设计比在代码里手写 if/else 更容易扩展，也更适合长期维护。

它的几个关键特性可以概括为：

支持自定义请求格式，默认格式是 {subject, object, action}；
将权限系统拆分为两个核心概念：model 和 policy；
支持 RBAC 的多层角色继承，不仅主体可以有角色，资源也可以有角色；
支持超级用户，例如 root 或 Administrator，这类用户可以不受普通授权策略限制；
内置 keyMatch 等操作符，适合处理路径型资源匹配，例如让 /foo/bar 映射到 /foo*。

如果你的系统里既有后台角色权限，又有接口路径匹配、资源分组或者多层继承关系，PHP-Casbin 的抽象会更有价值。它不是简单的“角色表 + 权限表”工具，而是一套更通用的授权判定引擎。

它不负责什么，以及为什么这点很重要

很多团队接触权限框架时，最容易混淆的就是“认证”和“授权”边界。PHP-Casbin 对这个边界划分得非常明确：它只做访问控制，不做身份认证。

具体来说，它不处理下面两类事情：

不负责 authentication，也就是用户名、密码、登录态这类身份验证流程；
不负责管理用户列表或角色列表，这些数据仍然由你的业务系统自己维护。

这意味着，PHP-Casbin 更适合放在现有业务系统的授权层中使用。你的登录模块、用户体系、组织架构可以继续沿用原来的实现；而在真正需要判断是否允许访问时，再把用户、资源、动作交给 Casbin 做统一裁决。

这种职责划分的好处很直接：权限规则不会和登录逻辑、用户管理逻辑搅在一起。对于中大型项目来说，这能减少后期维护时的耦合成本，也方便在多服务、多语言环境里复用同一套授权思路。

安装与最小可运行示例

PHP-Casbin 的安装方式很直接：

用四张纸卡说明 PHP-Casbin 的接入步骤，包括初始化 Enforcer、执行 enforce 判断、传入三类参数和查询角色。 — **PHP-Casbin 的最小接入路径**真正接入业务时，核心动作并不多：加载模型与策略，在关键节点调用 enforce()，再用管理。

composer require casbin/casbin

安装完成后，可以先用一个最简单的示例理解它的工作方式。

1. 初始化 Enforcer

Casbin 的核心入口是 Enforcer。初始化时需要传入两个参数：模型文件路径和策略文件路径。

展示 Casbin 的多语言生态与使用边界，一侧是 PHP、Go、Java、Node.js、Python，另一侧标明认证和用户管理不由 Casbin 负责。 — **跨语言生态与职责边界**Casbin 的价值不只在 PHP 项目里复用权限逻辑。

$e = new Enforcer(__DIR__ . '/examples/modelandpolicy/basic_model.conf', __DIR__ . "/examples/modelandpolicy/basic_policy.csv");

这里的关键点在于：模型定义“如何判定”，策略定义“谁拥有什么权限”。这也是它和普通权限库最不一样的地方。

2. 在业务代码中执行权限判断

真正接入项目时，通常只需要在受保护的业务节点加入授权判断：

$sub = "alice"; // the user that wants to access a resource.
$obj = "data1"; // the resource that is going to be accessed.
$act = "read"; // the operation that the user performs on the resource.
if ($e->enforce($sub, $obj, $act) === true) {
    // permit alice to read data1
} else {
    // deny the request, show an error
}

这里的三个参数分别对应：