Mastering PHP-Casbin: A Lightweight, Cross‑Framework Permission Solution

Common Permission Pitfalls

Hard‑coded logic

Developers often embed role checks directly in code, such as:

// Order list permission check (project snippet)
if ($user->role == 'admin') {
    // admin sees all orders
    $orders = Order::all();
} elseif ($user->role == 'merchant') {
    // merchant sees own orders
    $orders = Order::where('merchant_id', $user->merchant_id)->get();
} elseif ($user->role == 'customer_service') {
    // customer service sees assigned orders
    $orders = Order::where('cs_id', $user->id)->get();
}

Adding a new role (e.g., an operations role that can view unpaid orders across merchants) requires updating every similar block, leading to bugs if any location is missed.

Single model limitation

Many projects start with a simple RBAC model, but later need ACL, attribute‑based (ABAC) checks, or RESTful method restrictions. Without a flexible framework, developers write ad‑hoc patches, resulting in tangled permission logic.

No dynamic permissions

Urgent business requests—such as granting a merchant temporary access to another merchant’s orders for three days—usually force developers to add special cases or create temporary tables, reducing system flexibility.

Framework incompatibility

Maintaining separate permission code for different frameworks (e.g., Laravel vs. Gin+Gorm) leads to duplicated effort and inconsistent policies.

Core Capabilities of PHP‑Casbin

Support for multiple access‑control models

ACL : Simple user‑resource authorization (e.g., "User A can edit article 1").

RBAC : Role‑based access control for multi‑role scenarios (e.g., "Admin can view all orders, merchant can view only own orders").

RBAC with Domains : Multi‑tenant isolation by treating each tenant as a domain.

ABAC : Attribute‑based dynamic permissions (e.g., "User can view only their unexpired orders").

RESTful : HTTP‑method based API control (e.g., "GET /api/orders allowed, POST /api/orders admin only").

Lightweight, non‑intrusive integration

PHP‑Casbin's core package is only a few kilobytes and has no heavy dependencies. Install it via Composer: composer require casbin/casbin It works with major PHP frameworks such as Laravel, ThinkPHP, Yii2, Webman, Hyperf, EasySwoole, and even plain PHP.

For Laravel, integration requires three steps:

# 1. Install the Laravel adapter
composer require casbin/laravel-authz

# 2. Publish configuration and run migrations
php artisan vendor:publish
php artisan migrate

# 3. Perform an enforcement check
if (Enforcer::enforce('eve', 'articles', 'edit')) {
    // permit eve to edit articles
} else {
    // deny the request
}

The same policy files and model definitions are used across frameworks, and policies can be stored in files, MySQL, Redis, MongoDB, etc., simply by changing the storage adapter.

Dynamic permission management

Permissions can be added, removed, or modified at runtime without code changes:

// Grant read permission on /order to user bob
$enforcer->addPolicy('bob', '/order', 'read');

// Assign the admin role to bob
$enforcer->addRoleForUser('bob', 'admin');

// Deny the same permission explicitly
$enforcer->addPolicy('bob', '/order', 'read', 'deny');

// Batch delete permissions
$enforcer->removePolicies([
    ['bob', '/order', 'read']
]);

Performance optimizations

Rule cache : Frequently used rules can be cached in Redis to avoid database lookups on each check.

Batch check : Multiple permission checks can be evaluated in a single call, reducing I/O overhead.

Real‑World Scenarios

Case 1 – E‑commerce platform (multi‑role isolation)

A large e‑commerce SaaS with 500k+ daily active users uses PHP‑Casbin to enforce a four‑level hierarchy: platform admin, merchant, customer service, and buyer. The "RBAC with Domains" model binds each merchant to its own domain, ensuring strict data isolation.

Case 2 – SaaS API gateway

A SaaS provider managing 200+ APIs assigns permissions per subscription tier, integrates with JWT at the gateway layer, and automatically expands API access when customers upgrade. Policies such as "GET /api/v1/*" are defined once and applied globally.

Case 3 – Government system (dynamic & audit)

For a sensitive government application, RBAC handles static role permissions while ABAC adds time‑based constraints (e.g., edits only allowed between 09:00‑18:00). The matcher includes a time check:

[matchers]
m = g(r.sub, p.sub) && r.obj == p.obj && r.act == p.act && r.now >= "09:00" && r.now <= "18:00"

When enforcing, the current time is passed as an attribute:

$enforcer->enforce('user1', '/data', 'edit', ['now' => date('H:i')]);

Conclusion

PHP‑Casbin provides a unified, language‑agnostic solution that covers ACL, RBAC, ABAC, and other models. Its lightweight core, dynamic policy engine, and cross‑framework adapters make it ideal for micro‑service and cloud‑native architectures, allowing developers to manage permissions centrally without modifying application code.