DEV Community: Hossein Hezami

Fixing a Vue 3 Memory Leak in Large Lists: shallowRef and Virtualization

Hossein Hezami — Sun, 30 Aug 2026 17:47:26 +0000

Your application runs butter-smooth during local development. With fifty mock items in your data store, CPU utilization flatlines and memory graphs look like a flat, healthy plateau. Then you deploy to production, connect a high-frequency WebSocket stream pumping five hundred telemetry events per second, and watch the tab’s heap allocation climb by twenty megabytes every minute. After two hours, the browser tab freezes, Chrome throws an out-of-memory crash, and your user is forced to hard-refresh.

This is not a sudden garbage collection glitch. It is the cumulative effect of deep reactivity overhead mixed with unchecked DOM node retention in large v-for iterations. When building long-lived Vue 3 Single Page Applications that ingest continuous data streams, defaulting to standard ref() calls across massive datasets is an architectural trap.

The Reactivity Bloat Trap

Vue 3 replaced Vue 2's getter/setter tree traversal with native ES6 Proxy objects. Proxies are remarkably fast, but their convenience hides a significant memory tax. When you pass a massive array of objects to standard ref() or reactive(), Vue recursively walks every nested property of every object, wrapping them in nested getter/setter traps.

For an array of 5,000 records containing nested metadata and coordinates, Vue generates tens of thousands of active Proxy wrappers. Every time a backend payload updates an item, the reactivity system traverses those Proxies, schedules queue updates, and forces the Virtual DOM to evaluate diffs across the entire structural tree.

Consider this standard state declaration:

import { ref } from 'vue';

interface TelemetryItem {
  id: string;
  timestamp: number;
  metrics: {
    cpu: number;
    memory: number;
    load: number;
  };
  tags: string[];
}

// The trap: Deep proxying thousands of incoming items
const telemetryStream = ref<TelemetryItem[]>([]);

function ingestBatch(newBatch: TelemetryItem[]) {
  telemetryStream.value.push(...newBatch);
}

Every object pushed into telemetryStream.value is aggressively proxied. If your data pipeline replaces or mutates these items at high frequency, the garbage collector cannot easily reclaim memory because internal proxy references linger across component re-renders and closure boundaries.

Diagnosing the Root Cause

When investigating a vue 3 memory leak large lists scenario, console logs won't help. Drop into Chrome DevTools, open the Memory panel, and take a Heap Snapshot before and after simulating load.

If you inspect the snapshot and filter constructors by Proxy, you will often find thousands of detached DOM nodes and proxy instances lingering long after parent components have unmounted. This usually happens due to three compounding factors:

Deep Proxy Overhead: Storing large read-heavy or append-only datasets inside standard ref() instances.
Unstable Array Keys: Using array indices instead of unique primary keys inside v-for directives, which confuses the patch algorithm during high-frequency updates.
Orphaned Event Listeners: Child components within list items registering global window or event bus listeners without cleaning them up on onUnmounted.

Solving Deep Reactivity with shallowRef

If your application treats incoming data streams as immutable collections—meaning you replace the array wholesale or push batches rather than mutating deeply nested properties piece by piece—you should abandon deep reactivity for that dataset.

shallowRef() opts out of recursive proxy conversion. It only tracks reactivity on its .value property itself. Replacing the entire array triggers updates, but modifying an inner property will not.

Here is how you refactor list state using shallowRef and manual trigger control:

import { shallowRef, triggerRef } from 'vue';

interface TelemetryItem {
  id: string;
  timestamp: number;
  metrics: {
    cpu: number;
    memory: number;
    load: number;
  };
}

// The fix: Only the container reference is reactive
const telemetryStream = shallowRef<TelemetryItem[]>([]);

function ingestBatch(newBatch: TelemetryItem[]) {
  telemetryStream.value = [...telemetryStream.value, ...newBatch];

  // Keep memory footprint bounded by slicing old records
  if (telemetryStream.value.length > 2000) {
    telemetryStream.value = telemetryStream.value.slice(-1500);
  }
}

function updateSingleMetric(id: string, newCpu: number) {
  const items = telemetryStream.value;
  const target = items.find(item => item.id === id);
  if (target) {
    target.metrics.cpu = newCpu;
    // Explicitly notify watchers since deep reactivity is disabled
    triggerRef(telemetryStream);
  }
}

By switching to shallowRef, you bypass the creation of thousands of nested proxy wrappers, reducing heap allocations and flattening CPU spikes during bulk data ingestions.

Integrating Virtualization Correctly

Optimizing reactivity is only half the battle. If your DOM contains 5,000 rendered nodes simultaneously, the browser style recalculation and layout phases will stutter regardless of your JavaScript state management.

Virtual scrolling ensures that only items visible within the viewport are rendered to the DOM. When implementing a virtual list in Vue 3, ensure your v-for loop relies exclusively on stable, unique identifiers:

<template>
  <RecycleScroller
    class="scroller"
    :items="telemetryStream"
    :item-size="64"
    key-field="id"
    v-slot="{ item }"
  >
    <TelemetryRow :data="item" />
  </RecycleScroller>
</template>

Using a reliable key-field guarantees that Vue reuses existing DOM elements instead of destroying and recreating them on every scroll event or array shift.

Lifecycle Auditing and Component Cleanup

Even with shallowRef and virtualization, child components inside long lists often leak memory through forgotten event listeners, active timers, or third-party observers.

If a list item registers a ResizeObserver or a timer, it must explicitly clean up those resources before unmounting:

<script setup lang="ts">
import { onMounted, onUnmounted, ref } from 'vue';

const props = defineProps<{ data: TelemetryItem }>();

let intervalId: number | null = null;
const containerRef = ref<HTMLElement | null>(null);

const observer = new ResizeObserver(() => {});

onMounted(() => {
  if (containerRef.value) {
    observer.observe(containerRef.value);
  }

  intervalId = window.setInterval(() => {},
  5000);
});

onUnmounted(() => {
  observer.disconnect();

  if (intervalId !== null) {
    clearInterval(intervalId);
  }
});
</script>

Omitting observer.disconnect() leaves the component instance, its closure scope, and its associated DOM subtree anchored in memory indefinitely.

Production Verification

Before shipping high-throughput Vue 3 interfaces, run a comparative heap allocation test:

Open Chrome DevTools and navigate to the Memory tab.
Take a baseline heap snapshot.
Simulate your data stream for 5 minutes.
Force garbage collection using the trash can icon in DevTools.
Take a second heap snapshot and compare objects allocated against the baseline.

If you see an upward trend in detached HTML elements or retained ReactiveEffect instances, verify your state containers are using shallowRef and that all child lifecycles properly dispose of side effects.

🚨 10 Authorization Anti-Patterns I Keep Finding in Laravel Apps (And the One-Line Fixes That Save Them)

Hossein Hezami — Sun, 23 Aug 2026 17:39:26 +0000

TL;DR: After reviewing hundreds of Laravel codebases, the same 10 authorization mistakes show up again and again. This article walks through each anti-pattern with real before/after code — and shows how a single package, Laravel Permission Manager, fixes all ten out of the box.

🔗 GitHub Repository · 📦 Packagist

📋 Table of Contents

The Pattern Behind the Patterns
Anti-Pattern #1: The if ($user->is_admin) Sprawl
Anti-Pattern #2: The God Role
Anti-Pattern #3: Role Explosion
Anti-Pattern #4: The Scattered Policy
Anti-Pattern #5: The Cache Trap
Anti-Pattern #6: The "Works on My Machine" Tenant
Anti-Pattern #7: The Silent Deny
Anti-Pattern #8: The Regex Wildcard Hell
Anti-Pattern #9: The Missing Audit Trail
Anti-Pattern #10: The 3 AM Debug Session
One Package, Ten Fixes
Comparison with Spatie
Final Thoughts

🔁 The Pattern Behind the Patterns

I've reviewed a lot of Laravel authorization code. Startup MVPs. Enterprise SaaS platforms. Government portals. Fintech apps. The tech stacks differ, the domains differ, the team sizes differ — but the authorization mistakes are almost identical.

It's not because developers are careless. It's because authorization is one of those problems that looks trivial on day 1 and becomes a monster by month 12. You start with if ($user->is_admin). You end up with 47 roles, scattered policies, stale caches, and support tickets you can't explain.

This article collects the 10 anti-patterns I see most often, with real before/after code. If you recognize more than three of them in your own codebase — this article is for you.

🚫 Anti-Pattern #1: The `if ($user->is_admin)` Sprawl

The symptom

Your controllers look like a bowl of spaghetti:

public function index()
{
    if (!auth()->user()->is_admin && !auth()->user()->is_manager) {
        abort(403);
    }
    // ...
}

public function edit($id)
{
    $post = Post::findOrFail($id);
    if (!auth()->user()->is_admin && $post->user_id !== auth()->id()) {
        abort(403);
    }
    // ...
}

public function delete($id)
{
    if (!auth()->user()->is_admin) {
        abort(403);
    }
    // ...
}

Same logic, written 14 different ways, in 23 different files.

Why it breaks

Inconsistency: Every controller reinvents the check.
Untestable: You have to test each controller separately.
Brittle: When a new "senior editor" role is added, you hunt down 40 files.

The fix

Use a single, declarative authorization check:

public function index()
{
    abort_unless(auth()->user()->hasPermissionTo('posts.view'), 403);
}

public function edit(Post $post)
{
    abort_unless(auth()->user()->canPermission('posts.edit', $post), 403);
}

Or even cleaner — middleware:

Route::resource('posts', PostController::class)
    ->middleware('pm:permission:posts.view');

🚫 Anti-Pattern #2: The God Role

The symptom

You have a single admin role that can do everything — from managing users to editing blog posts to exporting financial reports.

// Somewhere in a seeder
$admin->assignPermission([
    'users.*', 'posts.*', 'billing.*', 'reports.*', 'system.*',
    // ... 200 more lines
]);

Why it breaks

Security risk: A compromised admin account has the keys to the kingdom.
No granularity: You can't give someone "admin for billing" but not "admin for users."
Audit nightmare: "Admin did something bad" tells you nothing.

The fix

Use role hierarchy instead of one mega-role:

$superAdmin = Role::create(['name' => 'Super Admin']);
$billingAdmin = Role::create(['name' => 'Billing Admin']);
$contentAdmin = Role::create(['name' => 'Content Admin']);

$superAdmin->inheritFrom('billingAdmin');
$superAdmin->inheritFrom('contentAdmin');

$billingAdmin->assignPermission(['billing.*', 'invoices.*']);
$contentAdmin->assignPermission(['posts.*', 'categories.*']);

Now super-admin inherits everything through composition, and you can promote someone to billing-admin without handing them the kingdom.

🚫 Anti-Pattern #3: Role Explosion

The symptom

Your database has 47 roles, and they all look like this:

admin
admin-no-delete
admin-no-billing
admin-except-reports
senior-editor
senior-editor-no-publish
junior-editor
junior-editor-drafts-only
...

Each role exists because someone said "I need an admin who can't delete users" — and the only tool in the toolbox was "create a new role."

Why it breaks

Cognitive overload: No one can remember what each role does.
Maintenance hell: Changing one permission requires updating 15 roles.
User confusion: "Why am I a senior-editor-no-publish?"

The fix

Add explicit deny as a first-class concept:

// One role, one exception
$user->assignRole('admin');
$user->denyPermissionTo('users.delete');

// The resolution order handles it:
// 1. Explicit User DENY   ← wins
// 2. Role ALLOW

One line replaces an entire "admin-no-delete" role.

🚫 Anti-Pattern #4: The Scattered Policy

The symptom

Authorization logic is smeared across policies, controllers, middleware, and blade files:

// PostPolicy.php
public function update($user, $post) {
    return $user->id === $post->user_id;
}

// PostController.php
public function update(Request $request, Post $post) {
    if ($post->status === 'published' && !$user->is_admin) {
        abort(403); // Wait, this isn't in the policy?
    }
    // ...
}

// post/edit.blade.php
@if ($post->user_id === auth()->id() || auth()->user()->is_admin)
    <button>Edit</button>
@endif

Three different files, three different rules. They'll eventually drift.

Why it breaks

Drift: The policy, controller, and UI drift out of sync.
Hidden rules: Some rules only exist in one place.
Debugging hell: "Why can I see the button but not submit the form?"

The fix

One source of truth — ABAC conditions stored in the database:

PermissionCondition::create([
    'permission_id' => Permission::findByRoute('posts.update')->id,
    'conditions' => [
        'any' => [
            ['field' => 'user.id', 'operator' => '=', 'value' => 'resource.user_id'],
            ['field' => 'user.role', 'operator' => '=', 'value' => 'admin'],
        ],
    ],
]);

Now the controller, the policy, the middleware, and the blade directive all use the same rule:

$user->canPermission('posts.update', $post);

🚫 Anti-Pattern #5: The Cache Trap

The symptom

You cache permissions to speed things up:

$permissions = Cache::remember("user.{$user->id}.permissions", 3600, function () use ($user) {
    return $user->roles->flatMap->permissions->pluck('route')->unique();
});

Then an admin revokes a role. The user still has the permission for the next hour. Support ticket incoming.

Why it breaks

Stale permissions: Cache doesn't know about mutations.
No cascade: Changing a role's permissions doesn't invalidate user caches.
Silent failures: The system is "correct" — just out of date.

The fix

Hierarchical cache invalidation that cascades through the dependency graph:

// When a role's permission changes:
$role->forgetCachedPermissions();
// Automatically:
// 1. Clears role's own cache
// 2. Clears ALL users with this role
// 3. Clears roles that INHERIT from this role
// 4. Clears users of those inherited roles

With cache tags (Redis/Memcached):

Cache::tags(["role:{$roleId}"])->flush();
Cache::tags(["user:{$userId}"])->flush();

And a CLI command to warm the cache on deploy:

php artisan permission:cache:warm

🚫 Anti-Pattern #6: The "Works on My Machine" Tenant

The symptom

In development, you test as a user who belongs to one tenant. Everything works.

In production, a user belongs to three tenants with different roles in each — and suddenly "admin" means different things in different contexts.

// Dev: simple
$user->assignRole('admin');

// Prod: chaos
// User is admin at Acme but viewer at Globex
// Which "admin" does `hasRole('admin')` check?

Why it breaks

Ambiguous context: Global roles don't model multi-tenant reality.
Privilege escalation: A viewer in one tenant may accidentally get admin access in another.
Data leaks: Users see data across tenants.

The fix

Team-scoped roles from day one:

$user->assignRoleForTeam('admin', $acme);
$user->assignRoleForTeam('viewer', $globex);

$user->hasRoleForTeam('admin', $acme);    // ✅ true
$user->hasRoleForTeam('admin', $globex);  // ❌ false

Set the active tenant via middleware:

Route::middleware(['pm.team:header,X-Team-Id'])->group(function () {
    // Every check inside is scoped
});

🚫 Anti-Pattern #7: The Silent Deny

The symptom

A user reports: "I can't see the Refunds page anymore."

You check their roles. They have finance-manager. The role has refunds.*. Everything should work. Yet hasPermissionTo('refunds.view') returns false.

You spend three hours tracing through code, only to find someone added a direct deny during a demo six weeks ago.

Why it breaks

Boolean blindness: false doesn't tell you why.
Hidden state: Deny rules, expiry, conditions — all invisible.
Time sink: Every incident becomes an archaeology dig.

The fix

Every check returns a rich result object, not a boolean:

$result = $user->authorizePermission('refunds.view');

$result->isDenied();    // true
$result->getReason();   // 'explicit_user_deny'
$result->getSource();   // 'direct_permission'
$result->getMetadata(); // ['permission_id' => 42, 'effect' => 'deny']

And from the terminal:

$ php artisan permission:why 42 refunds.view

  User:    42
  Ability: refunds.view
  ✗ DENIED
  Reason:  explicit_user_deny
  Source:  direct_permission

Mystery solved in 10 seconds.

🚫 Anti-Pattern #8: The Regex Wildcard Hell

The symptom

Your permission matching looks like this:

public function hasPermissionTo($permission) {
    foreach ($this->permissions as $p) {
        $regex = str_replace(['.', '*'], ['\.', '.*'], $p);
        if (preg_match('/^' . $regex . '$/', $permission)) {
            return true;
        }
    }
    return false;
}

It mostly works. Until someone adds admin.users.*.edit and it breaks. Or !users.delete (negation), which the regex can't express.

Why it breaks

Leaky abstraction: Regex is an implementation detail, not a contract.
No negation: "Everything except X" requires awkward workarounds.
No nesting: users.*.edit vs users.{id}.edit becomes a mess.

The fix

A dedicated wildcard engine with a clean syntax:

$matcher = app(WildcardMatcher::class);

$matcher->matches('users.*', 'users.edit');          // ✅
$matcher->matches('*.edit', 'users.edit');           // ✅
$matcher->matches('!users.delete', 'users.view');    // ✅ (negation!)
$matcher->matches('!users.delete', 'users.delete');  // ❌

The engine is tested in isolation, cached, and reused across trait, middleware, and CLI.

🚫 Anti-Pattern #9: The Missing Audit Trail

The symptom

A security audit asks: "Who granted billing.refund permissions in the last 90 days?"

You stare at the database. There's no record. The only clue is a row in role_permissions — with no timestamp, no actor, no IP.

Why it breaks

Compliance failure: SOC 2, ISO 27001, GDPR all require audit trails.
Forensics impossible: Can't reconstruct what happened.
Blame game: "Someone did it" isn't useful.

The fix

Automatic audit logging on every mutation:

// Every assignRole, givePermissionTo, etc. is automatically logged
PermissionAudit::byActor($adminId)->get();
PermissionAudit::action('granted')->where('effect', 'deny')->get();

Each record captures:

actor_id, action, subject_type, subject_id, role_id,
permission_id, effect, ip_address, user_agent, metadata, created_at

Compliance audit? Solved in one query.

🚫 Anti-Pattern #10: The 3 AM Debug Session

The symptom

It's 3 AM. A production incident. A user can't do something they should be able to do.

Your debugging toolkit:

dd($user->roles) → "Yep, has the role"
dd($user->permissions()) → "Yep, has the permission"
dd($user->hasPermissionTo('refunds.view')) → false???

Three hours later, you discover it was a cache issue, or an expired temporary permission, or a tenant context that got lost in a redirect.

Why it breaks

No observability: Authorization is a black box.
No snapshots: Can't freeze state for analysis.
No health checks: Problems fester until users report them.

The fix

A complete observability toolkit:

# Why was access denied?
php artisan permission:why 42 refunds.view

# What's this user's complete state?
php artisan permission:explain 42 refunds.view --json

# System-wide health check
php artisan permission:doctor

# Visualize the role hierarchy
php artisan permission:tree

And in code:

$snapshot = PermissionManager::snapshot($user);
// Roles, allow list, deny list, inherited roles, merged permissions — all in one object

3 AM becomes 3 minutes.

📦 One Package, Ten Fixes

Every anti-pattern above is solved by Laravel Permission Manager v2.0:

Anti-Pattern	The Fix
#1 `is_admin` sprawl	Declarative `hasPermissionTo()` + middleware DSL
#2 God Role	Role hierarchy with `inheritFrom()`
#3 Role explosion	Explicit `denyPermissionTo()` with deny-wins resolution
#4 Scattered Policy	ABAC conditions stored in DB, shared everywhere
#5 Cache trap	Hierarchical cache invalidation + tags + `cache:warm`
#6 Tenant chaos	Team-scoped roles + `pm.team` middleware
#7 Silent deny	`AuthorizationResult` with reason/source/metadata
#8 Regex hell	Dedicated `WildcardMatcher` with negation
#9 No audit	Automatic `PermissionAudit` on every mutation
#10 3 AM debugging	`permission:why` + `explain` + `doctor` + `snapshot`

composer require hosseinhezami/laravel-permission-manager

Supports Laravel 10, 11, 12, and 13, works with PHP 8.2+, and ships with 141 passing tests.

📊 Comparison with Spatie

For context, here's how the two packages handle these anti-patterns:

Feature	Laravel Permission Manager	Spatie Permission
RBAC	✅	✅
Direct Permissions	✅	✅
Explicit Allow/Deny	✅	❌
Role Hierarchy	✅ Multi-level + cycle detection	❌
Temporary Permissions	✅ Auto-expiry	❌
Teams / Multi-Tenancy	✅	✅
Multi-Guard (real)	✅ guard_name column	✅
ABAC / Conditions	✅ JSON engine (no eval)	❌
Audit Logging	✅ Built-in	❌
Authorization Trail	✅ Configurable	❌
Explain API	✅	❌
Permission Snapshot	✅	❌
CLI Doctor / Tree / Why	✅	❌
Permission Groups & Sets	✅	❌
Gate Integration	✅ Native	✅
Middleware DSL	✅ any/all/not	✅
Blade Directives	✅ 12+	✅
Testing Helpers	✅ Built-in	❌
Tests	141	~300
Laravel 13 Support	✅	⚠️
Backward Compatible	✅ 100%	✅

Bottom line: Spatie remains an excellent, battle-tested choice for standard RBAC. Laravel Permission Manager adds the enterprise layers — hierarchy, deny rules, ABAC, tenancy depth, auditing, and debugging — that Spatie doesn't cover.

💭 Final Thoughts

Authorization anti-patterns aren't mistakes. They're the natural consequence of starting simple and scaling without a plan.

Every Laravel app begins with if ($user->is_admin). The question isn't whether you'll hit these walls — it's when, and whether you'll have the tools to climb them.

The good news? You don't have to solve them one by one. A single cohesive package can handle all ten, and give you a foundation that scales from MVP to enterprise without rewrites.

Count how many anti-patterns you recognized in your own codebase:

0–2: You're in good shape. Keep watching.
3–5: Time to refactor before it hurts.
6–10: You know what to do. 🙂

composer require hosseinhezami/laravel-permission-manager

If this article helped you spot a few anti-patterns, a ⭐ on GitHub keeps the work going.

🔗 GitHub Repository · 📦 Packagist

Tags: #laravel #php #authorization #rbac #abac #security #webdev #antipatterns #refactoring #opensource #bestpractices #backend

The Laravel Authorization Cookbook: 12 Production-Ready Recipes for RBAC, ABAC, Teams & Deny Rules

Hossein Hezami — Sun, 23 Aug 2026 17:32:51 +0000

TL;DR: Authorization tutorials show you theory. Production apps need recipes. This cookbook gives you 12 copy-paste-ready patterns — from classic RBAC to owner-only ABAC rules, team-scoped admins, expiring contractor access, and audit trails — all built on Laravel Permission Manager. Every recipe includes the exact code you'd ship.

🔗 GitHub Repository · 📦 Packagist

📋 Table of Contents

Prep Your Kitchen (Installation)
Recipe 1: Classic RBAC with Wildcards
Recipe 2: The "One Exception" User
Recipe 3: The "Everything Except" Role
Recipe 4: Your Org Chart, as Code
Recipe 5: Owner-Only Editing (ABAC)
Recipe 6: Department-Scoped Approvals
Recipe 7: The Multi-Tenant Admin
Recipe 8: The 30-Day Contractor
Recipe 9: Bulletproof Route Protection
Recipe 10: Conditional UI Without the Mess
Recipe 11: The Compliance Trail
Recipe 12: The 2 AM Fix
Bonus Recipe: Testing Authorization
Comparison with Spatie
Final Thoughts

🔪 Prep Your Kitchen (Installation)

Every recipe below assumes this setup (takes ~60 seconds):

composer require hosseinhezami/laravel-permission-manager
php artisan vendor:publish --provider="HosseinHezami\PermissionManager\PermissionManagerServiceProvider" --tag="migrations"
php artisan migrate

// app/Models/User.php
use HosseinHezami\PermissionManager\Traits\PermissionTrait;

class User extends Authenticatable
{
    use PermissionTrait;
}

Now let's cook. 👨‍🍳

🍳 Recipe 1: Classic RBAC with Wildcards

Scenario: "Editors can do everything with posts."

Instead of listing ten permissions, use a wildcard:

use HosseinHezami\PermissionManager\Models\Role;

$editor = Role::create(['name' => 'Editor', 'slug' => 'editor']);

// One wildcard instead of ten lines
$editor->assignPermission('posts.*');

$user->assignRole('editor');

$user->hasPermissionTo('posts.view');    // ✅ true
$user->hasPermissionTo('posts.publish'); // ✅ true
$user->hasPermissionTo('users.delete');  // ❌ false

Chef's note: Wildcards support posts.*, *.edit, admin.*, and even * — matching happens in a dedicated engine, not scattered regex in your controllers.

🍳 Recipe 2: The "One Exception" User

Scenario: "Marketing needs report export, but only for Sarah this quarter."

Don't create a role for one person. Grant a direct permission:

$sarah->givePermissionTo('reports.export');

$sarah->hasDirectPermission('reports.export'); // ✅ true
$sarah->hasPermissionTo('reports.export');     // ✅ true (direct counts)

And when the quarter ends:

$sarah->revokePermissionTo('reports.export');

Chef's note: Direct permissions are checked alongside role permissions in the resolution chain — no special-casing in your code.

🍳 Recipe 3: The "Everything Except" Role

Scenario: "Interns get all post permissions, except delete."

This is where most RBAC systems collapse into role explosion. Here it's two lines, thanks to explicit deny:

$intern = Role::create(['name' => 'Intern', 'slug' => 'intern']);

$intern->assignPermission('posts.*');      // grant everything...
$intern->denyPermission('posts.delete');   // ...except this

$user->assignRole('intern');

$user->hasPermissionTo('posts.edit');   // ✅ true
$user->hasPermissionTo('posts.delete'); // ❌ false — deny always wins

Chef's note: The resolution order guarantees deny beats allow, at both user and role level. One rule eliminates dozens of "exception roles."

🍳 Recipe 4: Your Org Chart, as Code

Scenario: "Admins inherit everything editors can do; editors inherit everything viewers can do."

Model the hierarchy once — permissions cascade forever:

$viewer->assignPermission('posts.view');
$editor->assignPermission('posts.edit');
$admin->assignPermission('users.manage');

$editor->inheritFrom('viewer');
$admin->inheritFrom('editor');

// An admin now holds ALL of these:
$user->assignRole('admin');
$user->hasPermissionTo('posts.view');  // ✅ from viewer (2 levels down)
$user->hasPermissionTo('posts.edit');  // ✅ from editor (1 level down)
$user->hasPermissionTo('users.manage'); // ✅ direct

Visualize it anytime:

php artisan permission:tree

Chef's note: Cycles (A → B → A) throw a CyclicRoleInheritanceException instead of hanging your app. Safety is built in.

🍳 Recipe 5: Owner-Only Editing (ABAC)

Scenario: "Users can edit posts — but only their own."

Roles can't express "their own." Attribute-Based Access Control can:

use HosseinHezami\PermissionManager\Models\Permission;
use HosseinHezami\PermissionManager\Models\PermissionCondition;

PermissionCondition::create([
    'permission_id' => Permission::findByRoute('posts.update')->id,
    'name' => 'owner-only',
    'conditions' => [
        'field' => 'user.id',
        'operator' => '=',
        'value' => 'resource.owner_id',
    ],
]);

Now the check is resource-aware:

$user->canPermission('posts.update', $myPost);      // ✅ owns it
$user->canPermission('posts.update', $someoneElses); // ❌ not the owner

Chef's note: The condition engine is whitelist-based JSON — no eval(), no code injection. Safe by design.

🍳 Recipe 6: Department-Scoped Approvals

Scenario: "Managers approve expenses — but only for their own department, and only under $1,000."

Combine logical operators (all / any / not) and comparison operators:

PermissionCondition::create([
    'permission_id' => Permission::findByRoute('expenses.approve')->id,
    'name' => 'dept-manager-limit',
    'conditions' => [
        'all' => [
            ['field' => 'user.department_id', 'operator' => '=', 'value' => 'resource.department_id'],
            ['field' => 'resource.amount', 'operator' => '<=', 'value' => 1000],
        ],
    ],
]);

$manager->canPermission('expenses.approve', $teamExpense);    // ✅ same dept, $500
$manager->canPermission('expenses.approve', $otherDeptExpense); // ❌ different dept
$manager->canPermission('expenses.approve', $bigExpense);      // ❌ $5,000

Chef's note: Available operators: =, !=, >, >=, <, <=, in, not_in, contains, starts_with, ends_with, exists, not_exists.

🍳 Recipe 7: The Multi-Tenant Admin

Scenario: "Ana is an admin at Acme, but just a viewer at Globex."

Team-scoped roles make one user's permissions different per tenant:

use HosseinHezami\PermissionManager\Models\Team;

$acme = Team::createTeam(['name' => 'Acme Corp', 'slug' => 'acme']);
$globex = Team::createTeam(['name' => 'Globex Inc', 'slug' => 'globex']);

$ana->joinTeam($acme);
$ana->joinTeam($globex);

$ana->assignRoleForTeam('admin', $acme);
$ana->assignRoleForTeam('viewer', $globex);

$ana->hasRoleForTeam('admin', $acme);   // ✅
$ana->hasRoleForTeam('admin', $globex); // ❌

Scope every check in a request via middleware:

Route::middleware(['auth', 'pm.team:header,X-Team-Id'])->group(function () {
    // All permission checks inside respect the active team
});

🍳 Recipe 8: The 30-Day Contractor

Scenario: "The contractor needs billing access for one month. Make sure it dies on its own."

Temporary permissions auto-expire — no cron logic in your app code:

$contractor->givePermissionTo(
    'billing.view',
    'allow',
    now()->addDays(30)   // expires automatically
);

// Today: ✅ true
// Day 31: ❌ false — without you touching anything

Housekeeping (schedule weekly):

php artisan permission:prune --days=7

🍳 Recipe 9: Bulletproof Route Protection

Scenario: "Different routes need AND / OR / NOT permission logic."

The Middleware DSL expresses boolean logic declaratively:

// OR — any of these
Route::get('/reports', [ReportController::class, 'index'])
    ->middleware('pm:permission:any:reports.view|reports.export');

// AND — all of these
Route::post('/projects', [ProjectController::class, 'store'])
    ->middleware('pm:permission:all:projects.view|projects.create');

// NOT — must NOT have this
Route::get('/public', fn () => '...')
    ->middleware('pm:permission:not:admin.panel');

// Role + permission combined
Route::delete('/projects/{project}', [ProjectController::class, 'destroy'])
    ->middleware(['pm:role:admin', 'pm:permission:projects.delete']);

Unauthorized users get a clean 403 automatically.

🍳 Recipe 10: Conditional UI Without the Mess

Scenario: "Show buttons only for what the user can actually do."

Replace nested @if spaghetti with semantic directives:

@role('admin')
    <a href="{{ route('admin.settings') }}">Settings</a>
@endrole

@canpermission('posts.update', $post)
    <button wire:click="edit({{ $post->id }})">Edit</button>
@endcanpermission

@hasanyrole(['admin', 'editor'])
    <div class="editor-toolbar">…</div>
@endhasanyrole

@unlesspermission('posts.delete')
    <span class="muted">Deleting is disabled for your account.</span>
@endunlesspermission

Chef's note: 12+ directives ship out of the box, including @hasallpermissions, @cannotpermission, and the legacy @hasRole / @hasPermission.

🍳 Recipe 11: The Compliance Trail

Scenario: "The auditor asks: who granted delete rights, and when?"

Every mutation is recorded automatically (actor, action, subject, IP, user agent, metadata):

use HosseinHezami\PermissionManager\Models\PermissionAudit;

// Everything that happened recently
PermissionAudit::latest()->limit(50)->get();

// Everything one admin did
PermissionAudit::byActor($adminId)->get();

// Only grants of deny rules
PermissionAudit::action('granted')->where('effect', 'deny')->get();

Enable it in config:

'audit' => ['enabled' => true, 'log_mutations' => true],

Chef's note: There's also an optional authorization trail (authorization_logging) that logs denied checks with sampling — perfect for spotting probing attempts without flooding logs.

🍳 Recipe 12: The 2 AM Fix

Scenario: "User 42 can't delete posts. Why?"

Stop guessing. Ask the engine:

php artisan permission:why 42 posts.delete

  User:    42
  Ability: posts.delete
  ✗ DENIED
  Reason:  explicit_user_deny
  Source:  direct_permission
  Details:
    - matched_pattern: posts.delete

Or programmatically:

$result = PermissionManager::explain($user, 'posts.delete');
// ['allowed' => false, 'reason' => 'explicit_user_deny', 'source' => ..., 'user' => [...]]

And for a full picture of any user's state:

$snapshot = PermissionManager::snapshot($user);
// roles, allow list, deny list, inherited roles, merged permissions

Chef's note: permission:doctor also scans the whole system for orphan roles, cycles, duplicates, and stale caches — run it in CI.

🎁 Bonus Recipe: Testing Authorization

Ship confidence with the built-in testing helpers:

use HosseinHezami\PermissionManager\Testing\InteractsWithPermissions;
use HosseinHezami\PermissionManager\Testing\PermissionAssertions;

class PostPolicyTest extends TestCase
{
    use InteractsWithPermissions, PermissionAssertions;

    public function test_intern_cannot_delete_posts(): void
    {
        $intern = $this->actingAsRole(['intern']);

        $this->assertHasPermission($intern, 'posts.edit');
        $this->assertDoesNotHavePermission($intern, 'posts.delete');

        $this->deleteJson('/posts/1')->assertStatus(403);
    }
}

The package itself is backed by 141 tests / 226 assertions on isolated SQLite.

📊 Comparison with Spatie

Feature	Laravel Permission Manager	Spatie Permission
RBAC + Wildcards	✅	✅
Direct Permissions	✅	✅
Teams / Multi-Tenancy	✅	✅
Explicit Allow/Deny	✅	❌
Role Hierarchy	✅ + cycle detection	❌
ABAC / Conditions	✅ JSON engine (no eval)	❌
Temporary Permissions	✅ Auto-expiry	❌
Audit Logging	✅ Built-in	❌
Explain API / Doctor / Tree	✅	❌
Permission Groups & Sets	✅	❌
Gate Integration	✅ Native	✅
Middleware DSL	✅ any/all/not	✅
Blade Directives	✅ 12+	✅
Testing Helpers	✅ Built-in	❌
Tests	141	~300
Laravel 13 Support	✅	⚠️
Backward Compatible	✅ 100%	✅

Bottom line: Spatie is a mature, excellent choice for standard RBAC. Laravel Permission Manager adds the production recipes above — deny rules, hierarchy, ABAC, tenancy depth, auditing, and debugging — in one cohesive engine.

💭 Final Thoughts

Authorization in production isn't one feature — it's a dozen recurring patterns. The packages that win are the ones that turn each pattern into two lines of declarative code instead of a custom policy class.

Keep this cookbook handy:

🎭 Wildcard RBAC for the norm
🎯 Direct permissions for exceptions
🚫 Explicit deny for "everything except"
🌳 Hierarchy for org charts
🧠 ABAC for ownership & context
🏢 Teams for tenants
⏱️ Expiry for contractors
🛡️ Middleware DSL for routes
🎨 Blade directives for UI
📝 Audit for compliance
🔍 Explain API for debugging

composer require hosseinhezami/laravel-permission-manager

If a recipe saved you time, a ⭐ on GitHub keeps the kitchen open. 🙏

🔗 GitHub Repository · 📦 Packagist

Tags: #laravel #php #authorization #rbac #abac #multitenancy #security #webdev #tutorial #opensource #saas #backend

The 5 Levels of Laravel Authorization: From Basic RBAC to ABAC, Role Hierarchy & Multi-Tenancy (2026 Edition)

Hossein Hezami — Fri, 21 Aug 2026 08:16:22 +0000

TL;DR: Authorization maturity isn't binary — it's a ladder. Most Laravel apps start at Level 1 (basic RBAC) and only discover they need Levels 2–5 when the codebase is already on fire. This guide walks through all five levels with real code, shows you how to self-assess your app, and introduces a single package — Laravel Permission Manager — that covers every level.

🔗 GitHub Repository · 📦 Packagist

📋 Table of Contents

Why Authorization Has "Levels"
Level 1: Basic RBAC
Level 2: Direct Permissions & Deny Rules
Level 3: Role Hierarchy
Level 4: Contextual Authorization (ABAC)
Level 5: Multi-Tenancy, Audit & Observability
Self-Assessment: What Level Is Your App?
One Package, All Five Levels
Quick Start
Comparison with Spatie
Final Thoughts

🤔 Why Authorization Has "Levels"

Every Laravel app begins with the same innocent line:

if ($user->is_admin) { ... }

And every serious Laravel app eventually ends up somewhere like this:

if (
    $user->hasRole('admin') ||
    ($user->hasRole('editor') && $post->status === 'draft' && $post->user_id === $user->id) ||
    ($user->hasRole('manager') && $post->department_id === $user->department_id)
) { ... }

That journey from line one to line five is what we call authorization maturity. It happens in predictable stages — and knowing the stages lets you design for them before they hurt.

Here are the five levels.

🥉 Level 1: Basic RBAC

The question it answers: "What kind of user is this?"

Role-Based Access Control is where everyone starts. Users get roles, roles get permissions.

// Assign
$user->assignRole('editor');

// Check
$user->hasRole('editor');              // true
$user->hasPermissionTo('posts.edit');  // true

With wildcards, it gets surprisingly far:

$editor->assignPermission('posts.*');

$user->hasPermissionTo('posts.view');    // ✅
$user->hasPermissionTo('posts.publish'); // ✅

Where Level 1 breaks

The moment someone says "this one editor shouldn't be able to delete posts", pure RBAC has no answer except creating a new role. Do that ten times and you have role explosion.

🚩 You've outgrown Level 1 when: you start naming roles like editor-no-delete or admin-except-billing.

🥈 Level 2: Direct Permissions & Deny Rules

The question it answers: "What about the exceptions?"

Level 2 adds two escape hatches that eliminate 80% of role explosion:

Direct Permissions (grant without a role)

// One user needs report export — no new role needed
$user->givePermissionTo('reports.export');

$user->hasDirectPermission('reports.export'); // ✅ true

Explicit Deny (the "except this one" rule)

// The editor role grants posts.* ...
// but this user must never delete:
$user->denyPermissionTo('posts.delete');

$user->hasPermissionTo('posts.edit');   // ✅ true  (from role)
$user->hasPermissionTo('posts.delete'); // ❌ false (deny wins)

The governing rule is simple and powerful:

⚖️ Deny always beats allow.

The resolution order

A well-designed Level 2 system evaluates in a strict priority:

1. Super Admin bypass
2. Explicit User DENY     ← highest
3. Explicit Role DENY
4. Explicit User ALLOW
5. Role ALLOW
6. Inherited permissions
7. Default: DENY          ← lowest

🚩 You've outgrown Level 2 when: you find yourself writing admin > manager > editor chains by hand, or duplicating permissions across a dozen similar roles.

🥇 Level 3: Role Hierarchy

The question it answers: "Why am I copying the same permissions into ten roles?"

Level 3 introduces inheritance: roles extend other roles, and permissions cascade automatically.

// Build the chain: super-admin → admin → editor → viewer
$editor->inheritFrom('viewer');
$admin->inheritFrom('editor');
$superAdmin->inheritFrom('admin');

// Assign permissions once, at the right level
$viewer->assignPermission('posts.view');
$editor->assignPermission('posts.edit');
$admin->assignPermission('posts.delete');

Now a super-admin user automatically holds every permission in the chain:

$user->assignRole('super-admin');

$user->hasPermissionTo('posts.view');   // ✅ from viewer (3 up)
$user->hasPermissionTo('posts.edit');   // ✅ from editor (2 up)
$user->hasPermissionTo('posts.delete'); // ✅ from admin (1 up)

Cycle detection matters

A hierarchy without safety checks is a footgun. A → B → A must throw, not hang:

$roleA->inheritFrom('roleB');
$roleB->inheritFrom('roleA');
// ❌ CyclicRoleInheritanceException

And you should be able to see the structure:

php artisan permission:tree

super-admin (4 permissions)
└── admin (6 permissions)
    └── editor (3 permissions)
        └── viewer (1 permissions)

🚩 You've outgrown Level 3 when: requirements say "users can edit their own posts", "managers approve only their department", or "only while the post is a draft". Roles can't express context.

💎 Level 4: Contextual Authorization (ABAC)

The question it answers: "Can this user do this to **that* specific thing?"*

Attribute-Based Access Control evaluates attributes of the user, the resource, and the environment — not just role membership.

The condition engine

Define rules as safe, declarative JSON (no eval(), whitelist-based operators):

use HosseinHezami\PermissionManager\Models\Permission;
use HosseinHezami\PermissionManager\Models\PermissionCondition;

PermissionCondition::create([
    'permission_id' => Permission::findByRoute('posts.update')->id,
    'name' => 'owner-and-draft',
    'conditions' => [
        'all' => [
            ['field' => 'user.id', 'operator' => '=', 'value' => 'resource.owner_id'],
            ['field' => 'resource.status', 'operator' => '=', 'value' => 'draft'],
        ],
    ],
]);

Then check against a specific resource:

$user->canPermission('posts.update', $myDraftPost);    // ✅ owns it + draft
$user->canPermission('posts.update', $myPublishedPost);// ❌ not a draft
$user->canPermission('posts.update', $someoneElsesPost);// ❌ not the owner

The operator toolbox

Category	Operators
Equality	`=`, `!=`
Comparison	`>`, `>=`, `<`, `<=`
Collections	`in`, `not_in`, `contains`
Strings	`starts_with`, `ends_with`
Existence	`exists`, `not_exists`

Plus logical composition — all (AND), any (OR), not (negate) — nestable to any depth:

['all' => [
    ['field' => 'resource.status', 'operator' => '!=', 'value' => 'archived'],
    ['any' => [
        ['field' => 'user.id', 'operator' => '=', 'value' => 'resource.owner_id'],
        ['field' => 'user.role', 'operator' => '=', 'value' => 'admin'],
    ]],
]]

Custom abilities for full control

For logic that outgrows JSON, register closures:

PermissionManager::define('posts.update', function ($user, $post) {
    return $post->user_id === $user->id || $user->hasPermissionTo('posts.edit.any');
});

🚩 You've outgrown Level 4 when: the business says "the same person is an admin at Company A but just a viewer at Company B" — or "prove to the auditor who changed what, when."

🏆 Level 5: Multi-Tenancy, Audit & Observability

The question it answers: "Whose system are we even in — and who changed it?"

The top level is really three capabilities that enterprise apps can't live without.

5a. Team-scoped roles (Multi-Tenancy)

$acme = Team::createTeam(['name' => 'Acme Corp']);
$globex = Team::createTeam(['name' => 'Globex Inc']);

$user->joinTeam($acme);
$user->joinTeam($globex);

// Different role per tenant
$user->assignRoleForTeam('admin', $acme);
$user->assignRoleForTeam('viewer', $globex);

$user->hasRoleForTeam('admin', $acme);    // ✅
$user->hasRoleForTeam('admin', $globex);  // ❌

Scope every check to the active tenant via middleware or code:

Route::middleware(['pm.team:header,X-Team-Id'])->group(function () {
    // All checks inside are tenant-scoped
});

// or
PermissionManager::setTeam($currentTeam);

5b. Audit logging (compliance)

Every mutation is recorded automatically — actor, action, subject, IP, user agent, metadata:

PermissionAudit::byActor($adminId)->latest()->get();
PermissionAudit::action('granted')->get();

5c. Observability (debugging)

When a ticket says "user can't access X", you answer in seconds, not hours:

php artisan permission:why 42 posts.delete

  ✗ DENIED
  Reason:  explicit_user_deny
  Source:  direct_permission
  Details:
    - matched_pattern: posts.delete

Plus permission:doctor for system-wide health checks and permission snapshots for a complete picture of any user's state.

🏁 Level 5 is the ceiling — and very few packages reach it.

Self-Assessment: What Level Is Your App?

Check every statement that's true about your codebase:

Level 1

[ ] You use roles + permissions
[ ] You use wildcards like posts.*

Level 2

[ ] You can grant a permission to one user without a role
[ ] You can explicitly DENY something a role grants

Level 3

[ ] Roles inherit from other roles
[ ] Inheritance cycles are detected and rejected

Level 4

[ ] Permissions can depend on the resource (own posts only)
[ ] Conditions are declarative (no scattered if logic)

Level 5

[ ] A user can hold different roles in different tenants
[ ] Permission changes are audited automatically
[ ] You can explain why any decision was made

Scoring:

1 level: Normal for a young app — fine, but plan ahead.
2–3 levels: A growing product. You're feeling the pain points.
4–5 levels: Enterprise territory. Your authorization is a system, not an accident.

📦 One Package, All Five Levels

Most packages cover Level 1 (some Level 2). Laravel Permission Manager v2.0 implements all five in a single, cohesive engine:

Level	Feature	API
1	RBAC + wildcards	`assignRole()`, `hasPermissionTo()`
2	Direct + deny	`givePermissionTo()`, `denyPermissionTo()`
3	Hierarchy	`inheritFrom()`, `permission:tree`
4	ABAC	`canPermission($ability, $resource)`, `PermissionCondition`
5	Tenancy + audit + observability	`assignRoleForTeam()`, `PermissionAudit`, `permission:why`

It also ships the developer-experience layer that makes all of this maintainable:

🛡️ Advanced Middleware DSL (pm:permission:any:..., pm:role:...)
🎨 12+ Blade directives (@role, @canpermission, @unlesspermission)
🔐 Native Laravel Gate integration ($user->can(), @can)
⚡ Smart hierarchical cache invalidation
⏱️ Temporary permissions with auto-expiry
🧪 141 passing tests, 226 assertions
🔄 100% backward compatible with v1

🚀 Quick Start

composer require hosseinhezami/laravel-permission-manager
php artisan vendor:publish --provider="HosseinHezami\PermissionManager\PermissionManagerServiceProvider" --tag="migrations"
php artisan migrate

use HosseinHezami\PermissionManager\Traits\PermissionTrait;

class User extends Authenticatable
{
    use PermissionTrait;
}

Then climb the ladder at your own pace — every level is opt-in:

// Level 1
$user->assignRole('editor');

// Level 2
$user->denyPermissionTo('posts.delete');

// Level 3
$admin->inheritFrom('editor');

// Level 4
$user->canPermission('posts.update', $post);

// Level 5
$user->assignRoleForTeam('admin', $acme);

📊 Comparison with Spatie

Feature	Laravel Permission Manager	Spatie Permission
Level 1: RBAC + Wildcards	✅	✅
Level 2: Direct Permissions	✅	✅
Level 2: Explicit Deny	✅	❌
Level 3: Role Hierarchy	✅ + cycle detection	❌
Level 4: ABAC / Conditions	✅ JSON engine (no eval)	❌
Level 5: Teams / Multi-Tenancy	✅	✅
Level 5: Audit Logging	✅ Built-in	❌
Level 5: Explain API / Doctor	✅	❌
Temporary Permissions	✅ Auto-expiry	❌
Permission Groups & Sets	✅	❌
Gate Integration	✅ Native	✅
Middleware DSL	✅ any/all/not	✅
Blade Directives	✅ 12+	✅
Testing Helpers	✅ Built-in	❌
Tests	141	~300
Laravel 13 Support	✅	⚠️
Backward Compatible	✅ 100%	✅

Bottom line: Spatie is a mature, excellent choice for Levels 1–2 and basic tenancy. Laravel Permission Manager extends the ladder to Levels 3–5 — hierarchy, deny rules, ABAC, auditing, and observability — without sacrificing compatibility.

💭 Final Thoughts

Authorization isn't a feature you add once; it's a capability that matures with your product. The apps that suffer are the ones that discover Level 4 requirements while stuck in a Level 1 architecture.

The fix is to know the ladder — and pick tooling that lets you climb it without rewrites:

🥉 RBAC for identity
🥈 Direct + Deny for exceptions
🥇 Hierarchy for scale
💎 ABAC for context
🏆 Tenancy + Audit + Observability for enterprise

Wherever your app sits today, design for the level above it. Future-you will thank you.

composer require hosseinhezami/laravel-permission-manager

If this guide helped you map your authorization maturity, a ⭐ on GitHub means a lot!

🔗 GitHub Repository · 📦 Packagist ·

Tags: #laravel #php #authorization #rbac #abac #multitenancy #saas #security #webdev #opensource #tutorial #backend

Building a Multi-Tenant SaaS Authorization System in Laravel: A Complete Step-by-Step Guide (RBAC + ABAC + Teams)

Hossein Hezami — Thu, 20 Aug 2026 08:14:18 +0000

TL;DR: In this hands-on tutorial, we'll build a complete authorization system for a fictional multi-tenant SaaS app — "TaskFlow" — using Laravel Permission Manager. By the end, you'll have role hierarchy, team-scoped roles, conditional (ABAC) permissions, temporary access, audit logging, and debugging tools all working together. Full code included.

🔗 GitHub Repository · 📦 Packagist

📋 Table of Contents

What We're Building
Prerequisites
Step 1: Installation
Step 2: Designing the Role Hierarchy
Step 3: Creating Teams (Tenants)
Step 4: Team-Scoped Role Assignment
Step 5: Direct Permissions & Explicit Deny
Step 6: ABAC — Conditional Permissions
Step 7: Temporary Access for Contractors
Step 8: Protecting Routes with Middleware
Step 9: Blade Directives for the UI
Step 10: The Complete Controller
Step 11: Audit Logging
Step 12: Debugging with permission:why
Testing Everything
What We Built
Comparison with Spatie
Conclusion

🎯 What We're Building

Imagine TaskFlow, a project-management SaaS where:

🏢 Multiple companies (tenants) use the same app
👥 Each company has its own users with different roles
🌳 Roles follow a hierarchy (admin inherits editor's permissions)
🔒 Users can only edit their own tasks (contextual rule)
⏱️ Contractors get time-limited access
📝 Every permission change is audited
🐛 When something breaks, we can explain why access was denied

This is exactly the kind of authorization system that's painful to build by hand. Let's see how a modern package makes it almost declarative.

✅ Prerequisites

PHP 8.2+
Laravel 10, 11, 12, or 13
Basic understanding of Laravel (models, migrations, middleware)

📦 Step 1: Installation

composer require hosseinhezami/laravel-permission-manager

Publish and run migrations:

php artisan vendor:publish --provider="HosseinHezami\PermissionManager\PermissionManagerServiceProvider" --tag="config"
php artisan vendor:publish --provider="HosseinHezami\PermissionManager\PermissionManagerServiceProvider" --tag="migrations"
php artisan migrate

This creates 14 tables, including roles, permissions, user_permissions, role_inherits, teams, team_user, permission_conditions, and permission_audits.

Add the trait to your User model:

<?php

namespace App\Models;

use HosseinHezami\PermissionManager\Traits\PermissionTrait;
use Illuminate\Foundation\Auth\User as Authenticatable;

class User extends Authenticatable
{
    use PermissionTrait;
}

✅ Done. The foundation is ready.

🌳 Step 2: Designing the Role Hierarchy

Instead of creating dozens of flat roles, we build a hierarchy so permissions cascade naturally.

<?php

use HosseinHezami\PermissionManager\Models\Role;

// Create roles from lowest to highest
$viewer = Role::create(['name' => 'Viewer', 'slug' => 'viewer']);
$editor = Role::create(['name' => 'Editor', 'slug' => 'editor']);
$admin = Role::create(['name' => 'Admin', 'slug' => 'admin']);

// Build the hierarchy: admin → editor → viewer
$editor->inheritFrom('viewer');
$admin->inheritFrom('editor');

Now assign permissions at each level:

// Viewer: read-only
$viewer->assignPermission(['projects.view', 'tasks.view']);

// Editor: can create and edit (inherits viewer's permissions)
$editor->assignPermission(['tasks.create', 'tasks.edit']);

// Admin: full control (inherits editor + viewer)
$admin->assignPermission(['projects.create', 'projects.delete', 'members.manage']);

The magic: a user with the admin role automatically gets every permission from editor and viewer — no duplication.

$admin->hasPermissionTo('tasks.view'); // ✅ true (inherited from viewer)
$admin->hasPermissionTo('tasks.edit'); // ✅ true (inherited from editor)
$admin->hasPermissionTo('projects.delete'); // ✅ true (direct)

🛡️ The package also includes cycle detection, so A → B → A throws a CyclicRoleInheritanceException instead of crashing your app.

Visualize it anytime:

php artisan permission:tree

🏢 Step 3: Creating Teams (Tenants)

Each company in TaskFlow is a team:

<?php

use HosseinHezami\PermissionManager\Models\Team;

$acme = Team::createTeam(['name' => 'Acme Corp', 'slug' => 'acme']);
$globex = Team::createTeam(['name' => 'Globex Inc', 'slug' => 'globex']);

👥 Step 4: Team-Scoped Role Assignment

Here's where multi-tenancy shines. A user can hold different roles in different teams:

<?php

use App\Models\User;

$sarah = User::create([
    'name' => 'Sarah Connor',
    'email' => 'sarah@acme.com',
    'password' => bcrypt('secret'),
]);

// Sarah joins both companies
$sarah->joinTeam($acme);
$sarah->joinTeam($globex);

// She's an ADMIN at Acme, but only an EDITOR at Globex
$sarah->assignRoleForTeam('admin', $acme);
$sarah->assignRoleForTeam('editor', $globex);

Check roles per team:

$sarah->hasRoleForTeam('admin', $acme);    // ✅ true
$sarah->hasRoleForTeam('admin', $globex);  // ❌ false
$sarah->hasRoleForTeam('editor', $globex); // ✅ true

Setting the Active Tenant

In your controllers, tell the package which team is active. The cleanest way is middleware:

// routes/web.php
Route::middleware(['auth', 'pm.team:header,X-Team-Id'])->group(function () {
    // Every permission check inside is scoped to the team from the header
});

Or programmatically:

use HosseinHezami\PermissionManager\Facades\PermissionManager;

PermissionManager::setTeam($acme);
$sarah->hasPermissionTo('projects.delete'); // Evaluated in Acme's context

🔒 Step 5: Direct Permissions & Explicit Deny

Real products always have exceptions. Two tools handle them elegantly.

Direct Permissions (grant without a role)

// Sarah needs to export reports, but no role grants it
$sarah->givePermissionTo('reports.export');

$sarah->hasDirectPermission('reports.export'); // ✅ true

Explicit Deny (the "except this one" rule)

The CFO insists Sarah must never delete projects, even though her admin role allows it:

$sarah->denyPermissionTo('projects.delete');

// Now:
$sarah->hasPermissionTo('projects.create'); // ✅ true (from admin role)
$sarah->hasPermissionTo('projects.delete'); // ❌ false (explicit deny wins)

⚖️ Rule of thumb: Deny always beats allow. This one rule eliminates the need for dozens of "exception roles."

🧠 Step 6: ABAC — Conditional Permissions

Requirement: "Editors can edit tasks, but only their own, and only while the task is open."

This is contextual — it depends on the specific task. That's ABAC (Attribute-Based Access Control):

<?php

use HosseinHezami\PermissionManager\Models\Permission;
use HosseinHezami\PermissionManager\Models\PermissionCondition;

$editPermission = Permission::findByRoute('tasks.edit');

PermissionCondition::create([
    'permission_id' => $editPermission->id,
    'name' => 'own-open-tasks-only',
    'conditions' => [
        'all' => [
            ['field' => 'user.id', 'operator' => '=', 'value' => 'resource.assignee_id'],
            ['field' => 'resource.status', 'operator' => '!=', 'value' => 'completed'],
        ],
    ],
]);

Now the check is resource-aware:

$myOpenTask = Task::create(['assignee_id' => $sarah->id, 'status' => 'open']);
$myDoneTask = Task::create(['assignee_id' => $sarah->id, 'status' => 'completed']);
$otherTask = Task::create(['assignee_id' => 999, 'status' => 'open']);

$sarah->canPermission('tasks.edit', $myOpenTask);   // ✅ true
$sarah->canPermission('tasks.edit', $myDoneTask);   // ❌ false (completed)
$sarah->canPermission('tasks.edit', $otherTask);    // ❌ false (not hers)

🔒 The condition engine is whitelist-based — no eval(), no code injection. Only safe operators like =, !=, >, in, contains, exists.

⏱️ Step 7: Temporary Access for Contractors

A contractor needs billing access for 30 days:

$contractor = User::create([...]);

$contractor->givePermissionTo(
    'billing.view',
    'allow',
    now()->addDays(30)   // auto-expires
);

// Today:
$contractor->hasPermissionTo('billing.view'); // ✅ true

// In 31 days (no code change needed):
$contractor->hasPermissionTo('billing.view'); // ❌ false

Clean up expired records weekly with a scheduled command:

php artisan permission:prune --days=7

🛡️ Step 8: Protecting Routes with Middleware

The package ships with an expressive Middleware DSL:

<?php

use Illuminate\Support\Facades\Route;

// Single permission
Route::get('/projects', [ProjectController::class, 'index'])
    ->middleware('pm:permission:projects.view');

// ANY of these (OR)
Route::get('/reports', [ReportController::class, 'index'])
    ->middleware('pm:permission:any:reports.view|reports.export');

// ALL of these (AND)
Route::post('/projects', [ProjectController::class, 'store'])
    ->middleware('pm:permission:all:projects.view|projects.create');

// Role-based
Route::get('/members', [MemberController::class, 'index'])
    ->middleware('pm:role:admin');

// Combined: must be admin AND have the permission
Route::delete('/projects/{project}', [ProjectController::class, 'destroy'])
    ->middleware(['pm:role:admin', 'pm:permission:projects.delete']);

Unauthorized users automatically receive a 403.

🎨 Step 9: Blade Directives for the UI

Show only what users can actually do:

{{-- resources/views/projects/show.blade.php --}}

@role('admin')
    <a href="{{ route('members.index') }}" class="btn">Manage Members</a>
@endrole

@canpermission('tasks.edit', $task)
    <button @click="editTask({{ $task->id }})">Edit Task</button>
@endcanpermission

@hasanyrole(['admin', 'editor'])
    <div class="editor-toolbar">...</div>
@endhasanyrole

@unlesspermission('projects.delete')
    <span class="text-muted">Deleting is disabled for your account.</span>
@endunlesspermission

No more scattered @if ($user->is_admin) logic.

🧩 Step 10: The Complete Controller

Here's everything working together in one controller:

<?php

namespace App\Http\Controllers;

use App\Models\Task;
use App\Models\Team;
use HosseinHezami\PermissionManager\Facades\PermissionManager;
use Illuminate\Http\Request;

class TaskController extends Controller
{
    public function update(Request $request, string $teamSlug, Task $task)
    {
        // 1. Resolve and set the active tenant
        $team = Team::where('slug', $teamSlug)->firstOrFail();
        PermissionManager::setTeam($team);

        $user = $request->user();

        // 2. Role check within the tenant
        if (! $user->hasAnyRole(['admin', 'editor'])) {
            abort(403, 'You need an editor role in this team.');
        }

        // 3. Contextual (ABAC) check against the resource
        if (! $user->canPermission('tasks.edit', $task)) {
            abort(403, 'You can only edit your own open tasks.');
        }

        // 4. Perform the update
        $task->update($request->validated());

        return response()->json(['status' => 'updated']);
    }
}

Three layers of authorization — tenant, role, and context — in under 10 lines.

📝 Step 11: Audit Logging

Every mutation is recorded automatically:

$sarah->assignRole('admin');           // logged
$sarah->denyPermissionTo('projects.delete'); // logged
$admin->assignPermission('users.*');   // logged

Query the trail:

use HosseinHezami\PermissionManager\Models\PermissionAudit;

// Who granted what, recently?
PermissionAudit::latest()->limit(20)->get();

// Everything a specific admin did
PermissionAudit::byActor($adminId)->get();

// Only grants
PermissionAudit::action('granted')->get();

Each record stores the actor, action, subject, IP address, user agent, and JSON metadata — perfect for compliance audits.

🐛 Step 12: Debugging with permission:why

Support ticket: "Sarah can't delete projects!" Instead of guessing, ask the engine:

php artisan permission:why 42 projects.delete

┌─────────────────────────────────────────────────┐
│  Permission Decision Explanation                │
└─────────────────────────────────────────────────┘

  User:    42 (Sarah Connor)
  Ability: projects.delete

  ✗ DENIED

  Reason:  explicit_user_deny
  Source:  direct_permission
  Details:
    - matched_pattern: projects.delete
    - permission_id: 15

  Resolution chain:
    ✓ Role 'admin' allows projects.* (would grant)
    ✗ User has explicit DENY on projects.delete
    → Final decision: DENY (deny wins)

Mystery solved in 2 seconds. There's also a health check:

php artisan permission:doctor

It detects orphan permissions, cyclic inheritance, duplicates, expired grants, and cache inconsistencies.

🧪 Testing Everything

The package ships with testing helpers so your own test suite stays clean:

<?php

use HosseinHezami\PermissionManager\Testing\InteractsWithPermissions;
use HosseinHezami\PermissionManager\Testing\PermissionAssertions;

class TaskAuthorizationTest extends TestCase
{
    use InteractsWithPermissions, PermissionAssertions;

    public function test_editor_can_edit_own_open_task(): void
    {
        $editor = $this->actingAsRole(['editor']);
        $task = Task::create(['assignee_id' => $editor->id, 'status' => 'open']);

        $this->assertCanPermission($editor, 'tasks.edit', $task);
    }

    public function test_editor_cannot_edit_completed_task(): void
    {
        $editor = $this->actingAsRole(['editor']);
        $task = Task::create(['assignee_id' => $editor->id, 'status' => 'completed']);

        $this->assertCannotPermission($editor, 'tasks.edit', $task);
    }

    public function test_viewer_gets_403_on_create(): void
    {
        $this->actingAsRole(['viewer']);

        $this->postJson('/projects')->assertStatus(403);
    }
}

The package itself is backed by 141 passing tests and 226 assertions, all running on isolated SQLite in-memory databases.

🏁 What We Built

In one tutorial, we implemented:

Layer	Feature
Hierarchy	`admin → editor → viewer` inheritance
🏢 Tenancy	Team-scoped roles (`admin` at Acme, `editor` at Globex)
🔒 Exceptions	Direct permissions + explicit deny
🧠 Context	ABAC conditions (own + open tasks only)
⏱️ Time	Auto-expiring contractor access
🛡️ Routes	Middleware DSL (`any` / `all` / `not`)
🎨 UI	12+ Blade directives
📝 Compliance	Automatic audit logging
🐛 Debugging	`permission:why` + `permission:doctor`

That's a complete enterprise authorization stack — without writing a single custom policy class.

composer require hosseinhezami/laravel-permission-manager

📊 Comparison with Spatie

For those evaluating options, here's how the two packages compare:

Feature	Laravel Permission Manager	Spatie Permission
RBAC	✅	✅
Direct Permissions	✅	✅
Teams / Multi-Tenancy	✅	✅
Wildcard Permissions	✅ (advanced + negation)	✅
Explicit Allow/Deny	✅	❌
Role Hierarchy	✅ Multi-level + cycle detection	❌
Temporary Permissions	✅ Auto-expiry	❌
ABAC / Conditions	✅ JSON engine (no eval)	❌
Audit Logging	✅ Built-in	❌
Explain API	✅	❌
CLI Doctor / Tree	✅	❌
Permission Groups & Sets	✅	❌
Gate Integration	✅ Native	✅
Middleware DSL	✅ any/all/not	✅
Blade Directives	✅ 12+	✅
Testing Helpers	✅ Built-in	❌
Tests	141	~300
Laravel 13 Support	✅	⚠️
Backward Compatible	✅ 100%	✅

💬 Conclusion

Authorization in a multi-tenant SaaS isn't just "roles and permissions." It's hierarchies, exceptions, contexts, time limits, audits, and debugging — all at once.

Building that by hand means months of scattered policies and middleware. With the right package, it becomes a set of declarative, testable, auditable rules.

If you're building a SaaS or any app with complex access rules, give Laravel Permission Manager a try:

composer require hosseinhezami/laravel-permission-manager

And if you found this guide useful, a ⭐ on GitHub helps a lot!

🔗 GitHub Repository .

📦 Packagist ·

Tags: #laravel #php #saas #multitenancy #authorization #rbac #abac #tutorial #webdev #opensource #security #backend

5 Laravel Authorization Problems You're Probably Facing (And How to Solve Them in 2026)

Hossein Hezami — Wed, 19 Aug 2026 21:20:35 +0000

TL;DR: Most Laravel apps hit the same 5 authorization walls as they grow — role explosion, exception handling, multi-tenancy, contextual permissions, and debugging nightmares. This deep dive shows how to solve each one with modern patterns, and introduces a package that combines all solutions: Laravel Permission Manager.

🔗 GitHub · 📦 Packagist

📋 Table of Contents

Introduction: The Authorization Ceiling
Problem #1: The Role Explosion Trap
Problem #2: The "Except This One" Problem
Problem #3: The Multi-Tenant Nightmare
Problem #4: The "Can They Edit THIS Post?" Problem
Problem #5: The Silent Cache Bug
Bonus: The 3 AM Debugging Nightmare
The Complete Solution
Real-World Implementation
Comparison with Spatie
Final Thoughts

🎯 Introduction: The Authorization Ceiling

Every Laravel project starts with the same authorization story:

// Day 1: Simple and beautiful
if ($user->is_admin) {
    // show admin stuff
}

By month three, it looks like this:

// Month 3: Starting to hurt
if ($user->hasRole('admin') || 
    ($user->hasRole('editor') && $post->status === 'draft') ||
    ($user->hasRole('manager') && $post->department_id === $user->department_id)) {
    // ...
}

By year one, you've got authorization logic scattered across controllers, policies, middleware, and blade templates — with no clear source of truth.

This is what I call "The Authorization Ceiling": the point where basic RBAC stops working and you need something more sophisticated.

In this article, we'll explore the 5 most common authorization problems Laravel developers hit, why traditional solutions fail, and how modern patterns (and modern packages) solve them cleanly.

🔴 Problem #1: The Role Explosion Trap

The Symptom

Your application has roles: admin, editor, viewer. Life is good.

Then the product team asks:

"Can we have an admin who can't delete users?"
"Can we have an editor who can publish but not delete?"
"Can we have a viewer who can export reports?"

Before you know it, you have 47 roles in your database. Every new exception creates a new role. HR calls it "role explosion." You call it "nightmare fuel."

Why Traditional RBAC Fails

Pure RBAC assumes a clean mapping: User → Role → Permissions.

Real-world requirements look like this:
User → Role(s) → Permissions → EXCEPTIONS

The "exceptions" part is what breaks pure RBAC. You need a way to grant or deny permissions directly to users, independent of their roles.

The Solution: Direct Permissions + Role Composition

Modern authorization systems support two parallel permission channels:

// Channel 1: Role-based (the norm)
$user->assignRole('editor');
// Gets: posts.view, posts.create, posts.edit

// Channel 2: Direct permissions (the exception)
$user->givePermissionTo('reports.export');
$user->denyPermissionTo('posts.delete');

// Final result:
// - posts.view     ✅ (from role)
// - posts.create   ✅ (from role)
// - posts.edit     ✅ (from role)
// - posts.delete   ❌ (explicit deny wins!)
// - reports.export ✅ (direct grant)

The Resolution Order

The magic is in the resolution order. A well-designed system checks in this priority:

1. Super Admin bypass
2. Explicit User DENY        ← highest priority
3. Explicit Role DENY
4. Explicit User ALLOW
5. Role ALLOW
6. Inherited permissions
7. Default: DENY

Deny always wins over allow. This single rule eliminates 80% of role explosion.

🔴 Problem #2: The "Except This One" Problem

The Symptom

A manager tells you: "Give the marketing team access to everything in the CMS — except the ability to delete blog posts."

In basic RBAC, you have three bad options:

Create a new role (marketing-no-delete) — now you have 48 roles
Don't grant posts.delete — but then you can't use the convenient posts.* wildcard
Write custom middleware — now you have logic scattered everywhere

Why Wildcards Alone Don't Help

Wildcards are great for granting permissions:

$role->assignPermission('posts.*');  // Easy!

But they're useless for exceptions. You can't express "everything except X" with a simple wildcard.

The Solution: Explicit Deny with Wildcards

Modern systems combine wildcards with explicit deny:

// Grant everything in posts.*
$marketing->assignPermission('posts.*');

// But explicitly deny delete
$marketing->denyPermission('posts.delete');

// Or use negation wildcards (advanced)
$marketing->assignPermission('!posts.delete');

The Pattern in Action

// Senior Editor role
$seniorEditor = Role::create(['name' => 'Senior Editor']);
$seniorEditor->assignPermission([
    'posts.*',          // All post operations
    'categories.*',     // All category operations
    '!posts.delete',    // EXCEPT deleting posts
    '!posts.force-delete', // AND force-deleting
]);

// Now any user with this role:
$user->assignRole('senior-editor');

$user->hasPermissionTo('posts.view');         // ✅ true
$user->hasPermissionTo('posts.create');       // ✅ true
$user->hasPermissionTo('posts.edit');         // ✅ true
$user->hasPermissionTo('posts.publish');      // ✅ true
$user->hasPermissionTo('posts.delete');       // ❌ false (denied)
$user->hasPermissionTo('posts.force-delete'); // ❌ false (denied)

One role. Multiple exceptions. Zero role explosion.

🔴 Problem #3: The Multi-Tenant Nightmare

The Symptom

You're building a SaaS. Company A has their own users with their own roles. Company B has the same. But they're in the same database.

Suddenly you realize:

An "admin" in Company A should NOT be admin in Company B
A user might be admin in Company A but only a viewer in Company B
Permissions need to be scoped to a tenant

Why Global Roles Fail

Traditional RBAC treats roles as global:

$user->assignRole('admin');
// Admin everywhere. In every tenant. Forever.

For SaaS, you need:

$user->assignRoleForTeam('admin', $companyA);
$user->assignRoleForTeam('viewer', $companyB);

The Solution: Team-Scoped Roles

Modern multi-tenant authorization introduces a team context:

// Setup
$companyA = Team::createTeam(['name' => 'Acme Corp']);
$companyB = Team::createTeam(['name' => 'Globex Inc']);

// User belongs to both companies
$user->joinTeam($companyA);
$user->joinTeam($companyB);

// Different roles per company
$user->assignRoleForTeam('admin', $companyA);
$user->assignRoleForTeam('editor', $companyB);

// Check permissions in context
$user->hasRoleForTeam('admin', $companyA);   // ✅ true
$user->hasRoleForTeam('admin', $companyB);   // ❌ false
$user->hasRoleForTeam('editor', $companyB);  // ✅ true

Setting the Active Tenant

In controllers, you need to know which tenant is active:

// Option 1: Middleware (recommended)
Route::middleware(['pm.team:header,X-Team-Id'])->group(function () {
    // All permission checks here are scoped to the team from the header
});

// Option 2: Programmatic
PermissionManager::setTeam($currentTeam);
$user->hasPermissionTo('projects.delete'); // Scoped to $currentTeam

Database Design

The schema adds a team_id pivot column:

user_roles
├── user_id
├── role_id
├── team_id   ← THE key addition
└── expires_at

This lets one user have different roles in different tenants — without duplicating users.

🔴 Problem #4: The "Can They Edit THIS Post?" Problem

The Symptom

The requirement sounds simple: "Users can edit posts they own."

But it's deceptively complex:

"Own" is contextual — it depends on the specific post
A user might own Post A but not Post B
Admins can edit any post
Editors can edit their department's posts

Why Pure RBAC Can't Handle This

RBAC is binary: "Can the user do X? Yes or no."

But contextual authorization is conditional: "Can the user do X to Y?"

You need ABAC — Attribute-Based Access Control.

The Solution: Condition Engine

Modern systems define permissions with JSON conditions:

// Define the permission with a condition
PermissionCondition::create([
    'permission_id' => $permission->id,
    'name' => 'owner-only',
    'conditions' => [
        'field' => 'user.id',
        'operator' => '=',
        'value' => 'resource.owner_id',
    ],
]);

Then check it against a specific resource:

$user->canPermission('posts.edit', $post);
// Returns true ONLY if $user->id === $post->owner_id

Complex Conditions

Real-world rules are rarely simple:

// Rule: Users can edit posts they own, 
// BUT only if the post is in draft status,
// OR if the user is a department manager in the same department
PermissionCondition::create([
    'conditions' => [
        'any' => [
            // Condition 1: Owner + Draft
            ['all' => [
                ['field' => 'user.id', 'operator' => '=', 'value' => 'resource.owner_id'],
                ['field' => 'resource.status', 'operator' => '=', 'value' => 'draft'],
            ]],
            // Condition 2: Department manager
            ['all' => [
                ['field' => 'user.role', 'operator' => '=', 'value' => 'department-manager'],
                ['field' => 'user.department_id', 'operator' => '=', 'value' => 'resource.department_id'],
            ]],
        ],
    ],
]);

Supported Operators

A good condition engine supports:

Category	Operators
Equality	`=`, `!=`
Comparison	`>`, `>=`, `<`, `<=`
Collections	`in`, `not_in`, `contains`
Strings	`starts_with`, `ends_with`
Existence	`exists`, `not_exists`

Security Note

⚠️ Critical: The condition engine must be whitelist-based, never using eval() or dynamic code execution. JSON rules are interpreted, not executed.

🔴 Problem #5: The Silent Cache Bug

The Symptom

You change a role's permissions. Users still see old permissions for hours. Support tickets flood in.

Or worse: you revoke a user's admin role, but they can still access admin routes because the cache wasn't invalidated.

Why Naive Caching Fails

Basic cache strategies only invalidate the changed entity:

$role->assignPermission('users.delete');
$role->forgetCachedPermissions(); // Only clears role cache!

But what about the 500 users who have this role? Their user-level cache still says they don't have users.delete.

The Solution: Hierarchical Cache Invalidation

Modern systems use cascading invalidation:

// When you change a role's permission:
$role->forgetCachedPermissions();

// This should:
// 1. Clear the role's own cache
// 2. Clear cache for ALL users who have this role
// 3. Clear cache for roles that INHERIT from this role
// 4. Clear cache for users of those inherited roles

Cache Tags (When Available)

With Redis or Memcached, use cache tags for surgical invalidation:

Cache::tags(['role:42'])->flush();        // Everything tagged with role 42
Cache::tags(['user:123'])->flush();       // Everything for user 123
Cache::tags(['permissions:global'])->flush(); // Global permission list

Cache Warming

For production deployments, warm the cache proactively:

php artisan permission:cache:warm
# Preloads all role permissions, user permissions, etc.

🌟 Bonus: The 3 AM Debugging Nightmare

The Symptom

It's 3 AM. A user reports they can't access a feature they should have access to. You check:

✅ User has the editor role
✅ editor role has posts.publish permission
✅ User is logged in
❌ But hasPermissionTo('posts.publish') returns false

Why?!

The Solution: Explain API

Modern authorization systems include an Explain API that shows exactly why a decision was made:

$ php artisan permission:why 42 posts.publish

┌─────────────────────────────────────────────────┐
│  Permission Decision Explanation                │
└─────────────────────────────────────────────────┘

  User:    42 (John Doe)
  Ability: posts.publish

  ✗ DENIED

  Reason:  explicit_user_deny
  Source:  direct_permission
  Details:
    - matched_pattern: posts.publish
    - permission_id: 15
    - effect: deny
    - expires_at: null

  Resolution chain:
    ✓ Role 'editor' allows posts.* (would normally grant)
    ✗ User has explicit DENY on posts.publish
    → Final decision: DENY (explicit deny wins)

Suddenly it's obvious: someone added a direct deny permission to this specific user. Maybe during testing. Maybe by mistake. Now you know.

Programmatic Access

$result = PermissionManager::explain($user, 'posts.publish');

// Returns:
[
    'allowed' => false,
    'ability' => 'posts.publish',
    'reason' => 'explicit_user_deny',
    'source' => 'direct_permission',
    'metadata' => [
        'matched_pattern' => 'posts.publish',
        'permission_id' => 15,
    ],
    'user' => [
        'id' => 42,
        'roles' => ['editor'],
        'direct_permissions' => ['!posts.publish'],
    ],
]

Health Check Command

Go one step further with a "doctor" command:

$ php artisan permission:doctor

✓ No orphan permissions
✓ No orphan roles
✗ Cyclic role inheritance detected: A → B → A
✓ No duplicate roles
⚠ 15 expired permissions can be pruned
✓ Cache consistency OK

🎁 The Complete Solution

All five problems (and the bonus one) are solved by a single, cohesive package:

📦 Laravel Permission Manager v2.0

An enterprise-grade authorization engine that combines:

✅ RBAC + Direct Permissions + Allow/Deny
✅ Role Hierarchy with multi-level inheritance
✅ Teams / Multi-Tenancy
✅ ABAC with JSON-based Condition Engine
✅ Audit Logging for all changes
✅ Multi-Guard support
✅ Temporary Permissions with auto-expiry
✅ Explain API and CLI Doctor
✅ 141 passing tests with 226 assertions
✅ 100% backward compatible with v1

Quick Installation

composer require hosseinhezami/laravel-permission-manager
php artisan vendor:publish --provider="HosseinHezami\PermissionManager\PermissionManagerServiceProvider" --tag="migrations"
php artisan migrate

Add Trait

use HosseinHezami\PermissionManager\Traits\PermissionTrait;

class User extends Authenticatable
{
    use PermissionTrait;
}

💡 Real-World Implementation

Let's see how all these patterns work together in a real SaaS application.

Scenario: Multi-Tenant Project Management Tool

// Setup teams
$acme = Team::createTeam(['name' => 'Acme Corp']);
$globex = Team::createTeam(['name' => 'Globex Inc']);

// Setup role hierarchy
$viewer = Role::create(['name' => 'Viewer']);
$editor = Role::create(['name' => 'Editor']);
$admin = Role::create(['name' => 'Admin']);

$editor->inheritFrom('viewer');
$admin->inheritFrom('editor');

// Assign permissions
$viewer->assignPermission('projects.view');
$editor->assignPermission(['projects.edit', 'tasks.create']);
$admin->assignPermission(['projects.delete', 'members.manage']);

// A contractor joins both companies
$contractor = User::create([...]);
$contractor->joinTeam($acme);
$contractor->joinTeam($globex);

// Different roles per company
$contractor->assignRoleForTeam('admin', $acme);
$contractor->assignRoleForTeam('editor', $globex);

// Temporary 30-day access
$contractor->givePermissionTo(
    'billing.view', 
    'allow', 
    now()->addDays(30)
);

// Conditional permission: editors can only edit their own tasks
PermissionCondition::create([
    'permission_id' => Permission::findByRoute('tasks.edit')->id,
    'conditions' => [
        'all' => [
            ['field' => 'user.id', 'operator' => '=', 'value' => 'resource.assignee_id'],
            ['field' => 'resource.status', 'operator' => '!=', 'value' => 'completed'],
        ],
    ],
]);

Controller Example

class TaskController extends Controller
{
    public function update(Request $request, Team $team, Task $task)
    {
        // Set team context
        PermissionManager::setTeam($team);

        // ABAC check with resource
        if (!auth()->user()->canPermission('tasks.edit', $task)) {
            abort(403, 'You cannot edit this task');
        }

        $task->update($request->validated());

        // Audit log is automatic!
        return response()->json(['status' => 'updated']);
    }
}

Middleware Example

Route::middleware(['auth', 'pm.team:route,team', 'pm:role:admin|editor'])->group(function () {
    Route::get('/projects', [ProjectController::class, 'index']);
    Route::post('/projects', [ProjectController::class, 'store'])
        ->middleware('pm:permission:projects.create');
});

Blade Example

@role('admin')
    <a href="{{ route('admin.settings') }}">Admin Settings</a>
@endrole

@canpermission('tasks.edit', $task)
    <button @click="editTask({{ $task->id }})">Edit</button>
@endcanpermission

@hasanyrole(['admin', 'editor'])
    <div class="editor-toolbar">...</div>
@endhasanyrole

📊 Comparison with Spatie

Spatie's laravel-permission is the gold standard with 110M+ downloads. Here's how Laravel Permission Manager v2.0 compares:

Feature	Laravel Permission Manager	Spatie Permission
RBAC	✅	✅
Direct Permissions	✅	✅
Wildcard Permissions	✅ (advanced + negation)	✅
Explicit Allow/Deny	✅	❌
Role Hierarchy	✅ Multi-level + cycle detection	❌
Temporary Permissions	✅ Auto-expiry	❌
Teams / Multi-Tenancy	✅	✅
Multi-Guard (real)	✅ guard_name column	✅
ABAC / Conditions	✅ JSON engine (no eval)	❌
Audit Logging	✅ Built-in	❌
Authorization Trail	✅ Configurable	❌
Explain API	✅	❌
Permission Snapshot	✅	❌
CLI Doctor	✅	❌
CLI Why/Explain	✅	❌
Permission Tree	✅	❌
Resource Generator	✅	❌
Route Sync	✅ (3 strategies)	❌
Permission Groups	✅	❌
Permission Sets	✅	❌
Gate Integration	✅ Native	✅
Middleware DSL	✅ any/all/not	✅
Blade Directives	✅ 12+	✅
Smart Caching	✅ Hierarchical	✅
Testing Helpers	✅ Built-in	❌
Events	✅ 6 events	✅
Import/Export	✅ JSON	❌
Tests	141	~300
Laravel 13 Support	✅	⚠️
Backward Compatible	✅ 100%	✅

When to Choose Spatie

✅ Massive community support
✅ Extensive documentation
✅ Proven in production for years
✅ Lots of third-party integrations

When to Choose Laravel Permission Manager

✅ You need role hierarchy (Spatie doesn't have it)
✅ You need explicit deny (critical for exceptions)
✅ You need ABAC / conditional permissions
✅ You need built-in audit logging
✅ You need to debug why access was denied
✅ You want modern CLI tools (doctor, why, explain, tree)
✅ You need temporary permissions with auto-expiry
✅ You want 100% backward compatibility with v1

💭 Final Thoughts

Authorization is one of those problems that looks simple on day 1 and becomes a monster by month 12.

The five problems we explored — role explosion, exception handling, multi-tenancy, contextual permissions, and cache bugs — aren't edge cases. They're the inevitable evolution of every serious Laravel application.

The good news? You don't have to solve them one by one with custom code scattered across your codebase. Modern authorization packages like Laravel Permission Manager give you all the patterns in a single, cohesive system.

Key Takeaways

Pure RBAC isn't enough — you need direct permissions and explicit deny
Roles explode without deny rules — !posts.delete beats creating 50 roles
Multi-tenancy requires team context — global roles don't work for SaaS
ABAC handles contextual rules — JSON conditions, no eval(), no mess
Cache invalidation must be hierarchical — or you'll ship stale permissions
Debug tools are non-negotiable — the Explain API saves 3 AM debugging sessions

Next Steps

If any of these problems sound familiar, give Laravel Permission Manager a try:

composer require hosseinhezami/laravel-permission-manager

It supports Laravel 10, 11, 12, and 13, works with PHP 8.2+, and is 100% backward compatible — so it won't break your existing code.

🔗 GitHub Repository · 📦 Packagist

Tags: #laravel #php #authorization #rbac #abac #security #webdev #tutorial #opensource #saas

Found this helpful? Star ⭐ the GitHub repo and share it with your team!

The Most Advanced Laravel Permission Manager: Enterprise Authorization Engine with RBAC, ABAC, Role Hierarchy & Multi-Tenancy

Hossein Hezami — Wed, 19 Aug 2026 20:53:21 +0000

A complete, production-ready authorization platform for Laravel — combining RBAC, ABAC, Role Hierarchy, Teams, Audit Logging, and 30+ enterprise features in a single package. 141 tests. Zero breaking changes. Works with Laravel 10–13.

🔗 GitHub Repository · 📦 Packagist

📋 Table of Contents

Introduction
Quick Start (5 Minutes)
Core Authorization Features
Enterprise Features
Laravel Integration
Developer Experience
Architecture Overview
Real-World Examples
Testing & Quality
Installation & Configuration
Comparison with Spatie

🎯 Introduction

Laravel Permission Manager is the most advanced, enterprise-grade authorization engine available for Laravel applications. It goes far beyond basic role-based access control, delivering a complete authorization platform that combines:

🎭 RBAC (Role-Based Access Control)
🧠 ABAC (Attribute-Based Access Control)
🌳 Role Hierarchy with multi-level inheritance
🏢 Multi-Tenancy / Teams
📝 Audit Logging
⏱️ Temporary Permissions
🔒 Explicit Allow/Deny
🛡️ Advanced Middleware DSL

All in a single, cohesive, backward-compatible package with 141 passing tests and 226 assertions.

Whether you're building a simple blog or a complex SaaS platform with multiple tenants, conditional permissions, and strict audit requirements — this package handles it all.

composer require hosseinhezami/laravel-permission-manager

⚡ Quick Start (5 Minutes)

Step 1: Install & Publish

composer require hosseinhezami/laravel-permission-manager
php artisan vendor:publish --provider="HosseinHezami\PermissionManager\PermissionManagerServiceProvider" --tag="migrations"
php artisan migrate

Step 2: Add Trait to User Model

use HosseinHezami\PermissionManager\Traits\PermissionTrait;

class User extends Authenticatable
{
    use PermissionTrait;
}

Step 3: Create Roles & Assign Permissions

php artisan role:create admin "Administrator" "Full system access"
php artisan permission:create "users.view"
php artisan permission:create "users.edit"
php artisan role:assign-permission admin "users.view,users.edit"

Step 4: Assign Role & Check Access

$user->assignRole('admin');
$user->hasPermissionTo('users.view'); // true

That's it. A fully functional RBAC system in under 5 minutes. But this is just the surface...

🎯 Core Authorization Features

1. Role-Based Access Control (RBAC)

The foundation of the system. Multiple roles per user, permissions assigned to roles.

$user->assignRole('admin');
$user->assignRole(['editor', 'manager']);
$user->revokeRole('editor');

$user->hasRole('admin');                        // true
$user->hasAnyRole(['admin', 'super-admin']);    // true
$user->hasAllRoles(['admin', 'manager']);       // true
$user->lacksRole('super-admin');                // true

2. Direct User Permissions

Grant permissions directly to a user without needing a role. Perfect for exceptions, one-off access, or special cases.

// Grant direct permission
$user->givePermissionTo('reports.export');

// Check it
$user->hasDirectPermission('reports.export'); // true

// Deny directly
$user->denyPermissionTo('users.delete');

// Revoke
$user->revokePermissionTo('reports.export');

3. Explicit Allow / Deny System

The deny permission has higher priority than allow. This enables powerful exception-based access control.

// Role grants all posts.* permissions
$editor->assignPermission('posts.*');

// But this specific user cannot delete
$user->denyPermissionTo('posts.delete');

// Result:
$user->hasPermissionTo('posts.edit');   // ✅ true (from role wildcard)
$user->hasPermissionTo('posts.delete'); // ❌ false (explicit deny wins)

Resolution Order (highest → lowest priority):

1. Super Admin bypass
2. Explicit User DENY        ← highest
3. Explicit Role DENY
4. Explicit User ALLOW
5. Role ALLOW
6. Inherited Role permissions
7. Wildcard matching
8. Default: DENY             ← lowest

4. Wildcard Permissions

Flexible pattern matching with negation support:

$role->assignPermission('users.*');        // All user operations
$role->assignPermission('*.edit');         // All edit operations
$role->assignPermission('admin.*');        // All admin operations
$role->assignPermission('!users.delete');  // Everything EXCEPT users.delete

Pattern	Matches	Doesn't Match
`users.*`	`users.edit`, `users.delete`	`posts.edit`
`*.edit`	`users.edit`, `posts.edit`	`users.view`
`*`	Everything	Nothing
`!users.delete`	Everything except `users.delete`	`users.delete`

5. Role Hierarchy (Multi-Level Inheritance)

Roles can inherit from other roles, creating powerful permission chains:

// Build hierarchy: super-admin → admin → editor → viewer
$superAdmin->inheritFrom('admin');
$admin->inheritFrom('editor');
$editor->inheritFrom('viewer');

// Assign specific permissions at each level
$viewer->assignPermission('posts.view');
$editor->assignPermission('posts.edit');
$admin->assignPermission('posts.delete');
$superAdmin->assignPermission('system.config');

// A user with super-admin gets ALL permissions through the chain
$user->assignRole('super-admin');
$user->hasPermissionTo('posts.view');     // ✅ from viewer (3 levels up)
$user->hasPermissionTo('posts.edit');     // ✅ from editor (2 levels up)
$user->hasPermissionTo('posts.delete');   // ✅ from admin (1 level up)
$user->hasPermissionTo('system.config');  // ✅ from super-admin (direct)

Cycle Detection

The system automatically prevents circular inheritance:

$roleA->inheritFrom('roleB');
$roleB->inheritFrom('roleA'); 
// ❌ Throws CyclicRoleInheritanceException

6. Temporary / Expiring Permissions

Grant time-limited access that automatically expires:

// 24-hour access
$user->givePermissionTo('reports.export', 'allow', now()->addDay());

// 30-day contractor access
$user->givePermissionTo('projects.access', 'allow', now()->addDays(30));

// After expiration → automatically returns false
// No cron job needed for permission checks!

// Clean up expired records weekly
php artisan permission:prune --days=7

7. Super Admin Bypass

Configurable root access that skips all permission checks:

// config/permission-manager.php
'super_admin' => [
    'enabled' => true,
    'role_slug' => 'super-admin',
    'bypass_all' => true,
],

// Usage
$user->isSuperAdmin();                        // true
$user->hasPermissionTo('anything.xyz.123');   // true (bypasses everything)

🏢 Enterprise Features

8. Teams / Multi-Tenancy

Essential for SaaS applications where users belong to multiple organizations:

// Create teams
$engineering = Team::createTeam(['name' => 'Engineering', 'slug' => 'engineering']);
$marketing = Team::createTeam(['name' => 'Marketing', 'slug' => 'marketing']);

// User joins both teams
$user->joinTeam($engineering);
$user->joinTeam($marketing);

// Different roles per team
$user->assignRoleForTeam('admin', $engineering);
$user->assignRoleForTeam('editor', $marketing);

// Check team-specific roles
$user->hasRoleForTeam('admin', $engineering);   // true
$user->hasRoleForTeam('admin', $marketing);     // false
$user->hasRoleForTeam('editor', $marketing);    // true

// Leave team
$user->leaveTeam($marketing);

Team Context in Requests

// Via middleware
Route::middleware(['pm.team:header,X-Team-Id'])->group(function () {
    // All permissions scoped to team from X-Team-Id header
});

// Programmatically
PermissionManager::setTeam($currentTeam);
$user->hasPermissionTo('projects.view'); // Scoped to current team
PermissionManager::clearTeam();

9. ABAC (Attribute-Based Access Control)

The most powerful feature. Define conditions that must be met for a permission to grant access:

// Only allow editing if user owns the post AND it's a draft
PermissionCondition::create([
    'permission_id' => $permission->id,
    'name' => 'owner-and-draft',
    'conditions' => [
        'all' => [
            ['field' => 'user.id', 'operator' => '=', 'value' => 'resource.owner_id'],
            ['field' => 'resource.status', 'operator' => '=', 'value' => 'draft'],
        ],
    ],
]);

// Usage
$user->canPermission('posts.update', $post);
// Returns true ONLY if $user->id === $post->owner_id AND $post->status === 'draft'

Supported Operators

Operator	Description	Example
`=` `==`	Equal	`user.id = resource.owner_id`
`!=` `!==`	Not equal	`user.role != "banned"`
`>` `>=`	Greater than	`user.level >= resource.required_level`
`<` `<=`	Less than	`user.failed_attempts < 3`
`in`	In array	`resource.status in ["draft", "pending"]`
`not_in`	Not in array	`user.id not_in [1, 2, 3]`
`contains`	String contains	`user.email contains "@company.com"`
`starts_with`	String starts with	`resource.path starts_with "admin/"`
`exists`	Is not null	`resource.published_at exists`
`not_exists`	Is null	`resource.deleted_at not_exists`

Logical Operators & Nesting

// AND (all must match)
['all' => [...conditions]]

// OR (any must match)
['any' => [...conditions]]

// NOT (negate)
['not' => ...condition]

// Complex nesting
['all' => [
    ['field' => 'resource.status', 'operator' => '!=', 'value' => 'archived'],
    ['any' => [
        ['field' => 'user.id', 'operator' => '=', 'value' => 'resource.owner_id'],
        ['field' => 'user.role', 'operator' => '=', 'value' => 'admin'],
    ]],
]]

🔒 Security: The condition engine uses a whitelist-based evaluator. No eval(), no code execution. Only safe, predefined operators.

10. Audit Logging

Track every permission change with full context:

// Automatically logged when you:
$user->assignRole('admin');
$role->assignPermission('users.delete');
$user->givePermissionTo('reports.export');

// Query the audit trail
PermissionAudit::byActor($adminId)->get();
PermissionAudit::action('granted')->latest()->limit(50)->get();

// Each record includes:
// - actor_id (who made the change)
// - action (granted, revoked, created, etc.)
// - subject_type (user, role, permission)
// - ip_address, user_agent
// - metadata (JSON)

11. Authorization Audit Trail

Optionally log every permission check (not just mutations):

// config/permission-manager.php
'authorization_logging' => [
    'enabled' => true,
    'denied_only' => true,     // Only log failed attempts
    'sample_rate' => 0.1,      // Log 10% (for high-traffic apps)
],

12. Multi-Guard Support

True isolation between authentication guards:

// Create guard-specific roles
Role::create(['name' => 'Web Admin', 'slug' => 'web-admin', 'guard_name' => 'web']);
Role::create(['name' => 'API Admin', 'slug' => 'api-admin', 'guard_name' => 'api']);

// Query by guard
Role::forGuard('web')->get();
Role::forGuard('api')->get();
Permission::forGuard('api')->get();

13. Permission Groups & Sets

Organize hundreds of permissions logically:

// Groups (categories for UI)
$group = PermissionGroup::createGroup(['name' => 'User Management', 'slug' => 'user-mgmt']);
$permission->assignToGroup('user-mgmt');

// Sets (bundles for quick assignment)
$set = PermissionSet::createSet(['name' => 'Content Manager', 'slug' => 'content-manager']);
$set->assignPermissions(['posts.view', 'posts.create', 'posts.edit', 'posts.publish']);

// Assign entire set to a role
$role->assignPermissionSet('content-manager');

🔐 Laravel Integration

14. Native Gate Integration

All permissions automatically register with Laravel's Gate via Gate::before():

// These all work out of the box:
$user->can('users.edit');
$user->cannot('users.delete');

// In Blade
@can('users.edit')
    <button>Edit</button>
@endcan

// In Controllers
Gate::authorize('users.edit');
Gate::allows('users.edit');
Gate::denies('users.delete');

15. Advanced Middleware DSL

Protect routes with a powerful, expressive syntax:

// Single permission
Route::get('/users', fn() => '...')
    ->middleware('pm:permission:users.view');

// ANY of these (OR logic)
Route::get('/users', fn() => '...')
    ->middleware('pm:permission:any:users.view|users.list');

// ALL of these (AND logic)
Route::post('/users', fn() => '...')
    ->middleware('pm:permission:all:users.view|users.create');

// NOT this permission
Route::get('/public', fn() => '...')
    ->middleware('pm:permission:not:admin.panel');

// Role checks
Route::get('/admin', fn() => '...')
    ->middleware('pm:role:admin|manager|editor');

// Combined (AND between directives)
Route::get('/reports', fn() => '...')
    ->middleware(['pm:role:admin', 'pm:permission:reports.view']);

16. Blade Directives (12+)

@role('admin')
    <span>Welcome, Admin!</span>
@endrole

@permission('users.edit')
    <button>Edit User</button>
@endpermission

@hasanyrole(['admin', 'editor'])
    <span>You can edit content</span>
@endhasanyrole

@hasallroles(['verified', 'premium'])
    <span>Premium Verified User</span>
@endhasallroles

@unlesspermission('users.delete')
    <span class="text-muted">Delete disabled</span>
@endunlesspermission

@canpermission('posts.update', $post)
    <a href="{{ route('posts.edit', $post) }}">Edit</a>
@endcanpermission

17. Custom Abilities (Policy Integration)

Define complex authorization logic:

PermissionManager::define('posts.update', function ($user, $post) {
    return $post->user_id === $user->id 
        || $user->hasPermissionTo('posts.edit.any');
});

// Usage
$user->canPermission('posts.update', $post);

🛠️ Developer Experience

18. Explain API (Debugging)

Get detailed explanations of authorization decisions:

$result = PermissionManager::explain($user, 'orders.delete');

// Returns:
[
    'allowed' => false,
    'ability' => 'orders.delete',
    'reason' => 'explicit_user_deny',
    'source' => 'direct_permission',
    'metadata' => [
        'matched_pattern' => 'orders.delete',
        'permission_id' => 42,
    ],
    'user' => [
        'id' => 1,
        'roles' => ['admin', 'editor'],
        'direct_permissions' => ['orders.view', '!orders.delete'],
    ],
]

19. Permission Snapshot

Debug a user's complete authorization state:

$snapshot = PermissionManager::snapshot($user);
// Returns: roles, allow list, deny list, inherited roles, permissions, context

20. Rich CLI Commands (24 total)

# 🩺 System health check
php artisan permission:doctor

# 🌳 View role hierarchy tree
php artisan permission:tree

# ❓ Why was access denied?
php artisan permission:why 42 users.delete

# 📋 Explain permission (JSON output)
php artisan permission:explain 42 users.edit --json

# ✅ Validate configuration
php artisan permission:validate

# ✂️ Prune expired permissions
php artisan permission:prune --days=30

# ⚡ Cache management
php artisan permission:cache:warm
php artisan permission:cache:clear

# 📦 Generate CRUD permissions
php artisan permission:generate-resource users

# 🔄 Sync routes (3 strategies)
php artisan permission:sync-routes --strategy=controller-action

# Standard CRUD
php artisan role:create admin "Administrator"
php artisan permission:create "users.view"
php artisan role:assign-permission admin "users.*"
php artisan user:assign-role 1 admin
php artisan role:export roles.json
php artisan role:import roles.json

Example: `permission:why`

$ php artisan permission:why 42 users.delete

┌─────────────────────────────────────────────────┐
│  Permission Decision Explanation                │
└─────────────────────────────────────────────────┘

  User:    42
  Ability: users.delete

  ✗ DENIED

  Reason:  explicit_user_deny
  Source:  direct_permission
  Details:
    - matched_pattern: users.delete
    - permission_id: 15

21. Smart Caching

Hierarchical cache invalidation that actually works:

// When a permission changes:
// 1. Permission cache invalidated
// 2. All roles with that permission invalidated
// 3. All users with those roles invalidated

// Manual cache control
PermissionManager::cache()->flushAll();
PermissionManager::cache()->flushUser($userId);
PermissionManager::cache()->flushRole($roleId);

Supports Cache Tags for Redis/Memcached drivers.

22. Testing Helpers

Built-in helpers for application tests:

use HosseinHezami\PermissionManager\Testing\InteractsWithPermissions;
use HosseinHezami\PermissionManager\Testing\PermissionAssertions;

class PostControllerTest extends TestCase
{
    use InteractsWithPermissions;
    use PermissionAssertions;

    public function test_admin_can_edit_posts()
    {
        $admin = $this->createUserWithRoles(['admin']);

        $this->assertHasRole($admin, 'admin');
        $this->assertHasPermission($admin, 'posts.edit');
        $this->assertDoesNotHavePermission($admin, 'system.config');
    }

    public function test_unauthorized_gets_403()
    {
        $user = $this->createUser();

        $this->actingAs($user)
            ->get('/admin/users')
            ->assertStatus(403);
    }
}

23. Fluent Facade API

use HosseinHezami\PermissionManager\Facades\PermissionManager;

// Roles
PermissionManager::roles()->list();
PermissionManager::roles()->create(['slug' => 'admin', 'name' => 'Administrator']);
PermissionManager::role('admin')->assignPermission('users.*');
PermissionManager::role('admin')->inheritFrom('editor');

// Permissions
PermissionManager::permissions()->create('users.view');
PermissionManager::permissions()->sync();
PermissionManager::permissions()->generateResource('posts');

// Users
PermissionManager::user($userId)->assignRole('admin');
PermissionManager::user($userId)->hasPermission('users.edit');

// Authorization
PermissionManager::check($user, 'users.edit');
PermissionManager::explain($user, 'orders.delete');
PermissionManager::snapshot($user);

// Teams
PermissionManager::setTeam($team);
PermissionManager::clearTeam();

// Cache
PermissionManager::cache()->flushAll();

🏗️ Architecture Overview

The Authorization Engine

All permission checks flow through a single, centralized engine:

Request → Middleware / Gate / Blade
              ↓
     AuthorizationManager
              ↓
    ┌─────────────────────┐
    │ 1. Super Admin?     │ → BYPASS
    │ 2. User DENY?       │ → DENY
    │ 3. Role DENY?       │ → DENY
    │ 4. User ALLOW?      │ → ALLOW
    │ 5. Role ALLOW?      │ → ALLOW
    │ 6. Inherited?       │ → ALLOW
    │ 7. Conditions?      │ → EVALUATE
    │ 8. Default          │ → DENY
    └─────────────────────┘
              ↓
     AuthorizationResult
     (allowed, reason, source, metadata)

Database Schema (14 Tables)

roles                    permissions              permission_groups
role_permissions         user_roles               user_permissions
role_inherits            permission_sets           permission_set_items
teams                    team_user                permission_conditions
permission_audits        authorization_logs

Source Structure (73 files)

src/
├── Authorization/       (9 files - Core engine)
├── Console/            (24 files - CLI commands)
├── Events/             (6 files)
├── Exceptions/         (6 files)
├── Handlers/           (2 files)
├── Listeners/          (2 files)
├── Middleware/         (3 files)
├── Models/             (10 files)
├── Proxies/            (2 files)
├── Services/           (2 files)
├── Support/            (5 files)
├── Testing/            (2 files)
├── Traits/             (1 file)
└── Root files          (2 files)

💡 Real-World Examples

E-commerce Platform

// Hierarchy: super-admin > admin > seller > customer
$seller->inheritFrom('customer');
$admin->inheritFrom('seller');

// Conditional: sellers can only edit their own products
PermissionCondition::create([
    'permission_id' => Permission::findByRoute('products.edit')->id,
    'conditions' => [
        'field' => 'user.id',
        'operator' => '=',
        'value' => 'resource.seller_id',
    ],
]);

Multi-Tenant SaaS

$companyA = Team::createTeam(['name' => 'Company A']);
$companyB = Team::createTeam(['name' => 'Company B']);

$user->joinTeam($companyA);
$user->joinTeam($companyB);

$user->assignRoleForTeam('admin', $companyA);
$user->assignRoleForTeam('viewer', $companyB);

Contractor with Time-Limited Access

$contractor->givePermissionTo('projects.access', 'allow', now()->addDays(30));
$contractor->givePermissionTo('billing.view', 'allow', now()->addDays(7));
// Automatically expires. No cron job needed for checks.

Approval Workflow

// Managers can approve expenses under $1000
PermissionCondition::create([
    'permission_id' => Permission::findByRoute('expenses.approve')->id,
    'conditions' => [
        'all' => [
            ['field' => 'user.role', 'operator' => '=', 'value' => 'manager'],
            ['field' => 'resource.amount', 'operator' => '<=', 'value' => 1000],
        ],
    ],
]);

🧪 Testing & Quality

The package ships with 141 passing tests and 226 assertions:

✅ Unit Tests        → WildcardMatcher, ConditionEvaluator, MiddlewareParser, CacheKeys
✅ Feature Tests     → Trait, Models, Middleware, Blade, Commands, Gate, Proxy
✅ Integration Tests → Hierarchy, Teams, ABAC, Expiry, Cache, Audit

All tests run against SQLite in-memory — completely isolated, fast, and safe.

composer test              # All 141 tests
composer test-unit         # Unit only
composer test-feature      # Feature only
composer test-integration  # Integration only

📦 Installation & Configuration

Requirements

PHP 8.2+
Laravel 10, 11, 12, or 13

Install

composer require hosseinhezami/laravel-permission-manager

Publish & Migrate

php artisan vendor:publish --provider="HosseinHezami\PermissionManager\PermissionManagerServiceProvider" --tag="config"
php artisan vendor:publish --provider="HosseinHezami\PermissionManager\PermissionManagerServiceProvider" --tag="migrations"
php artisan migrate

Configuration Highlights

// config/permission-manager.php
return [
    'cache_duration' => 60,
    'wildcards' => true,

    'super_admin' => [
        'enabled' => true,
        'role_slug' => 'super-admin',
        'bypass_all' => true,
    ],

    'teams' => ['enabled' => true],
    'audit' => ['enabled' => true, 'log_mutations' => true],
    'conditions' => ['enabled' => true],

    'authorization_logging' => [
        'enabled' => false,
        'denied_only' => true,
        'sample_rate' => 1.0,
    ],
];

🔗 Links

🐙 GitHub: github.com/hosseinhezami/laravel-permission-manager
📦 Packagist: packagist.org/packages/hosseinhezami/laravel-permission-manager

📊 Comparison with Spatie Laravel Permission

Feature	Laravel Permission Manager	Spatie Permission
RBAC	✅	✅
Direct Permissions	✅	✅
Wildcard Permissions	✅ (advanced + negation)	✅
Explicit Allow/Deny	✅	❌
Role Hierarchy	✅ Multi-level + cycle detection	❌
Temporary Permissions	✅ Auto-expiry	❌
Teams / Multi-Tenancy	✅	✅
Multi-Guard (real)	✅ guard_name column	✅
ABAC / Conditions	✅ JSON engine (no eval)	❌
Audit Logging	✅ Built-in	❌
Authorization Trail	✅ Configurable	❌
Explain API	✅	❌
Permission Snapshot	✅	❌
CLI Doctor	✅	❌
CLI Why/Explain	✅	❌
Permission Tree	✅	❌
Resource Generator	✅	❌
Route Sync	✅ (3 strategies)	❌
Permission Groups	✅	❌
Permission Sets	✅	❌
Gate Integration	✅ Native	✅
Middleware DSL	✅ any/all/not	✅
Blade Directives	✅ 12+	✅
Smart Caching	✅ Hierarchical	✅
Testing Helpers	✅ Built-in	❌
Events	✅ 6 events	✅
Import/Export	✅ JSON	❌
Tests	141	~300
Laravel 13 Support	✅	⚠️
Backward Compatible	✅ 100%	✅

💬 Final Thoughts

Laravel Permission Manager v2.0 is not just another permission package. It's a complete enterprise authorization platform that handles everything from simple RBAC to complex ABAC with conditions, multi-tenancy, audit trails, and hierarchical role structures.

Whether you're building a startup MVP or a large-scale SaaS platform, this package scales with your needs — without requiring you to switch packages or write custom authorization logic.

composer require hosseinhezami/laravel-permission-manager

Star ⭐ it on GitHub if you find it useful!

🔗 GitHub Repository · 📦 Packagist

Built with ❤️ by Hossein Hezami · MIT License

Tags: laravel, php, authorization, rbac, abac, permissions, access-control, multi-tenancy, security, opensource, laravel-package, role-management

Moving Beyond TOTP: Why the PulseProof Sentinel (PPS) Protocol is the Future of Offline Authentication

Hossein Hezami — Wed, 29 Jul 2026 08:38:21 +0000

Time-based One-Time Passwords (TOTP)—the technology behind Google Authenticator and Microsoft Authenticator—have kept us safe for over a decade. But as cyber threats evolve and systems increasingly move to isolated, semi-offline, or edge environments, the foundational vulnerabilities of TOTP are starting to show.

Enter the PulseProof Sentinel Protocol (PPS), an innovative Internet-Draft registered with the IETF by researcher Hossein Hezami. PPS introduces an elegant shift in cryptographic paradigms: replacing shared-secret symmetric authentication with time-bound asymmetric proofs.

In this article, we’ll dive deep into why PPS is a game-changer, how it operates in 100% offline environments, and how it handles physical coercion with absolute stealth.

The Fatal Flaws of Traditional TOTP

To appreciate PulseProof Sentinel, we must first look at what makes traditional 2FA vulnerable:

The Shared Secret Trap: TOTP relies on a shared symmetric key stored on both your device and the server. If a hacker breaches the server’s database, they steal the raw seeds for every single user.
Lack of Forward Secrecy: If someone compromises your 2FA secret key today, they can often generate future codes or intercept past sessions.

3. No Safety Valve for Physical Coercion: If an attacker physically forces you to open your account under duress, traditional 2FA leaves you with zero options to signal for help safely.

What is PulseProof Sentinel (PPS)?

PulseProof Sentinel (PPS) is an experimental authentication protocol designed specifically for constraint-heavy, offline, or high-risk environments (like IoT networks, remote hardware, or air-gapped point-of-sale terminals).

Instead of generating a random 6-digit number based on a shared secret, PPS generates a cryptographically signed message known as a "Pulse."

1. Zero Server-Side Secrets (Asymmetric Architecture)PPS leverages asymmetric cryptography (Ed25519). The server stores only your Public Key. If the server's database is completely leaked, the attacker gains absolutely nothing that could help them spoof a pulse. Your Private Key remains strictly isolated within your device's Secure Enclave.

2. Time-Counter Hybrid RatchetingTo prevent replay attacks and ensure robust security, PPS uses an asymmetric ratchet mechanism based on SHA-256 and HKDF. Every time a pulse is generated, the private key evolves and the old key is discarded forever. This guarantees strict Forward Secrecy.

How It Works in 100% Offline Environments

One of the biggest engineering achievements of PPS is its ability to validate credentials without requiring any internet connection on the client side.

Imagine an air-gapped smart door lock or an offline POS machine in a remote area:

[ Offline Client Device ]
│ (Generates Compact CBOR Pulse via Ed25519)
▼
[ QR Code / NFC / BLE ]
│
▼
[ Air-Gapped Verifier Terminal ] ───► (Validates Signature via Local Public Key)

The Compact Pulse: The client packs the protocol version, timestamp, unique nonce, counter, and a signature into a highly compressed CBOR (Concise Binary Object Representation) payload.
Passive Data Transfer: This tiny payload is translated into a dynamic QR Code, an NFC burst, or a Bluetooth Low Energy (BLE) packet.
The Dynamic Acceptance Window: What happens if the offline device's internal clock drifts? PPS introduces a Sliding Validation Window. When the verifier receives a pulse, it checks a range of future/past time slots. Once validated, the verifier automatically calculates the exact time drift, saves it to the user's profile, and seamlessly self-corrects for future validations—all without internet sync!

The Coolest Feature: The "Honey-Pulse" (Duress Signaling)

In high-security deployments, physical threats are a real attack vector. PPS addresses this with a brilliant psychological and cryptographic mechanism called Honey-Pulse.

When configuring your device, PPS initiates twin, parallel key-rotation tracks:

Normal Track: For everyday, risk-free authentications.
Honey Track: Triggered only under duress (via an alternative PIN, a specific gesture, or a hidden panic button).

If an attacker forces you to log in, you trigger the Honey Track. The device outputs a pulse that looks mathematically flawless to any onlooker. The attacker sees a successful login animation on the device screen.

However, when the pulse hits the online backend server, it instantly flags the hidden "Honey" indicator. The server subtly sandboxes the session, caps transactional limits to zero, and quietly triggers silent alarms or relays location coordinates to security personnel—all while keeping the attacker completely oblivious.

Current Status and Developer Ecosystem

Because security standards require rigorous peer reviews, PPS is currently classified as an Experimental Internet-Draft within the IETF. It is undergoing active evaluation to ensure it stands up to side-channel attacks and edge-case vulnerabilities.

However, the ecosystem is growing fast. If you are a developer looking to experiment with this cutting-edge protocol, open-source packages are already available:

Core PHP Implementation: pps-php
Laravel Framework Integration: laravel-pps

Conclusion: Is This the Future?

While mass-market web apps are currently pivoting toward Passkeys (WebAuthn/FIDO2), PulseProof Sentinel bridges the critical gaps where FIDO2 cannot easily reach—specifically in completely air-gapped, zero-connectivity environments, and scenarios requiring native, cryptographically hidden duress handling.

It is a masterful piece of security architecture that proves we don't need to invent new math to solve complex problems; we just need to orchestrate the math we have more intelligently.

What are your thoughts on asymmetric offline 2FA? Do you think the Honey-Pulse mechanism should become a standard feature in all modern authentication apps? Let's discuss in the comments below! 👇

Beyond Passkeys and OTP: Why I Built a Protocol for the Authentication Gaps We Keep Ignoring

Hossein Hezami — Thu, 23 Jul 2026 20:09:09 +0000

Passkeys are winning the browser login race.

And they should.

WebAuthn and FIDO2 solved a huge part of the authentication problem: phishing-resistant, browser-native, public-key authentication.

But the more I worked on real systems, the more I noticed a gap.

Not every authentication problem happens inside a browser.

Some happen on a point-of-sale terminal.

Some happen offline.

Some happen inside a legacy OTP form that cannot be rewritten overnight.

Some happen during a high-value transaction where the user must visually confirm an amount.

Some happen under coercion.

And some require approval from more than one device.

That is the gap that led me to PulseProof Sentinel Protocol, or PPS.

PPS is an experimental open authentication protocol that replaces shared-secret TOTP-style codes with signed, time-bound, asymmetric proofs called Pulses.

You can explore the project here:

https://pps-protocol.github.io

The Problem With TOTP

TOTP is everywhere.

It is simple, widely supported, and easy to deploy.

But it has a structural weakness:

code = HMAC(shared_secret, time)

The server knows the secret.

If the server database is breached, the attacker can generate valid codes.

That is not ideal.

Public-key authentication solves this. The server should not need to know the secret that proves identity.

That is the core idea behind PPS:

Pulse = Sign(private_key, time + rp + nonce + counter + context + policy)

The user’s device holds the private key.

The server stores only the public key.

The proof is signed, time-bound, replay-protected, and bound to the relying party.

PPS Is Not a WebAuthn Replacement

This is important.

PPS is not trying to replace WebAuthn.

If you are building browser-based passwordless login, WebAuthn is usually the right answer.

PPS is designed to complement WebAuthn.

It targets the operational gaps where WebAuthn is unavailable, impractical, or insufficient:

offline authentication
legacy OTP input forms
QR-code and deep-link authentication
constrained hardware terminals
point-of-sale and IoT devices
human-visible transaction confirmation
silent duress signaling
offline multi-device threshold approval

In other words:

WebAuthn is for passkeys.

PPS is for the authentication flows that still live outside the passkey world.

What Is a Pulse?

A Pulse is a signed authentication statement.

It can be bound to several things:

a relying-party identifier
a time epoch
a server nonce
a monotonic counter
an expiration window
a security policy
a transaction hash
environmental context

This makes PPS flexible.

A Pulse can be used for simple login.

It can also be used for transaction signing, offline terminal authentication, or multi-device approval.

The protocol uses deterministic CBOR encoding and Ed25519 signatures.

The mandatory profile is:

PPS-ED25519-CBOR30

You can read the full specification here:

https://pps-protocol.github.io/pulseproof-sentinel/SPEC.html

The documentation is available here:

https://pps-protocol.github.io/pulseproof-sentinel/docs/

The protocol is also submitted as an IETF Internet-Draft:

https://datatracker.ietf.org/doc/draft-hezami-pulseproof-sentinel/

The Developer Story: PHP and Laravel

A protocol is only useful if people can implement it.

That is why the first sample implementation is available in PHP.

The core package is framework-agnostic:

https://github.com/pps-protocol/pps-php

You can install it with Composer:

composer require pps-protocol/pps-php

Package website:

https://pps-protocol.github.io/pps-php/

Documentation:

https://pps-protocol.github.io/pps-php/docs/

Packagist:

https://packagist.org/packages/pps-protocol/pps-php

For Laravel applications, there is a dedicated integration package:

https://github.com/pps-protocol/laravel-pps

Install it with:

composer require pps-protocol/laravel-pps

Then run:

php artisan pps:install

The Laravel package provides:

service provider
publishable configuration
API routes
HTTP controller
facade
Artisan commands
storage backend integration
transaction challenge endpoints
silent duress handling support

Laravel package website:

https://pps-protocol.github.io/laravel-pps/

Packagist:

https://packagist.org/packages/pps-protocol/laravel-pps

A Small Example

At the protocol level, the idea is simple.

The client signs a Pulse:

use Pps\Client\AuthenticatorClient;

$client = new AuthenticatorClient($clientState);

$pulse = $client
    ->rpId('example.com')
    ->nonce($nonceFromServer)
    ->createPulse();

The server verifies it using the stored public key.

No shared OTP secret is required.

In Laravel, the package exposes endpoints such as:

GET  /pps/health
GET  /pps/challenge
POST /pps/register
POST /pps/verify
POST /pps/transaction/challenge
POST /pps/transaction/verify

This makes it easy to integrate PPS into an existing authentication or transaction-signing flow.

Transaction Signing Is Where PPS Becomes Interesting

One of my favorite PPS features is transaction signing.

Imagine a withdrawal:

Amount: 2,500,067 IRR
Trust Code: 49371867

The last two digits of the Trust Code come from the transaction amount.

This creates a human-visible connection between the cryptographic proof and the transaction being approved.

The user can confirm:

Yes, the code I see matches the amount I requested.

This is especially useful for:

banking
fintech
crypto withdrawals
admin approvals
high-value payments
corporate treasury flows

PPS can bind the transaction hash, amount, session, and policy into the signed Pulse.

That is much stronger than sending a generic OTP code.

Silent Duress: Authentication Under Coercion

Another important area is duress.

What happens if someone is forced to authenticate?

Traditional OTP systems do not have a good answer.

PPS introduces an optional duress mechanism.

The user can authenticate with a hidden duress key.

The resulting Pulse is cryptographically valid, but the server recognizes it as a Honey-Pulse.

The server can return a normal-looking success response while internally:

restricting account capabilities
blocking high-value operations
delaying settlement
triggering a silent alert
preserving audit logs

This is sensitive territory, and implementation matters a lot.

But for high-risk accounts, it is a powerful concept.

Offline and Multi-Device Flows

PPS also supports offline authentication.

Because a Pulse is signed and time-bound, it can be generated without a live network round-trip.

Offline mode requires stricter rate limiting and careful operational design, but it is useful for:

terminals
IoT devices
field equipment
unstable networks
emergency access

PPS also supports offline multi-device threshold approval.

For example:

2-of-2: phone + watch
2-of-3: phone + laptop + hardware key

This is useful when a single device should not be enough to approve a sensitive action.

The Ecosystem

The PPS project is organized under a GitHub organization:

https://github.com/pps-protocol

The main repositories are:

PulseProof Sentinel Protocol

The specification repository.

https://github.com/pps-protocol/pulseproof-sentinel

Website:

https://pps-protocol.github.io/pulseproof-sentinel/

Specification:

https://pps-protocol.github.io/pulseproof-sentinel/SPEC.html

Documentation:

https://pps-protocol.github.io/pulseproof-sentinel/docs/

pps-php

The core PHP implementation.

https://github.com/pps-protocol/pps-php

Website:

https://pps-protocol.github.io/pps-php/

Documentation:

https://pps-protocol.github.io/pps-php/docs/

Packagist:

https://packagist.org/packages/pps-protocol/pps-php

laravel-pps

The Laravel integration package.

https://github.com/pps-protocol/laravel-pps

Website:

https://pps-protocol.github.io/laravel-pps/

Packagist:

https://packagist.org/packages/pps-protocol/laravel-pps

Why Explore PPS?

PPS is experimental.

It has not been independently audited.

It is not ready to replace your production authentication system tomorrow.

But if you care about authentication design, it is worth exploring.

It is especially interesting if you are working on:

fintech authentication
crypto exchange security
offline device login
POS terminals
IoT authentication
transaction signing
high-value approval workflows
duress-aware accounts
multi-device authorization
legacy OTP migration

PPS asks a simple question:

Why should the server ever store a shared OTP secret when it can verify a signature instead?

Start Here

The best place to start is the project website:

https://pps-protocol.github.io

Then read the specification:

https://pps-protocol.github.io/pulseproof-sentinel/SPEC.html

If you are a PHP developer, try the core package:

composer require pps-protocol/pps-php

If you are using Laravel, install the Laravel integration:

composer require pps-protocol/laravel-pps

And if you are interested in protocol design, review the IETF Internet-Draft:

https://datatracker.ietf.org/doc/draft-hezami-pulseproof-sentinel/

PPS is early, experimental, and open for feedback.

If you believe authentication should move beyond shared secrets, give it a look.

TOTP Secrets Are a Liability: Meet PPS, an Asymmetric Authentication Protocol for PHP and Laravel

Hossein Hezami — Thu, 23 Jul 2026 20:01:37 +0000

Most two-factor authentication systems still rely on a dangerous assumption:

If the server is breached, authentication secrets can be protected.

TOTP breaks that assumption.

With TOTP, the server stores a shared secret. If your database leaks, attackers can generate valid OTP codes.

That is exactly the problem PulseProof Sentinel Protocol, or PPS, tries to solve.

PPS is an experimental open authentication protocol that replaces shared-secret TOTP codes with signed, time-bound, asymmetric proofs called Pulses.

Instead of this:

TOTP:
  code = HMAC(shared_secret, time)

PPS uses this:

PPS:
  Pulse = Sign(private_key, time + rp + nonce + counter + context + policy)

The server never stores a shared OTP secret.

It stores only public keys.

What Is PPS?

PulseProof Sentinel Protocol is an asymmetric authentication protocol designed for scenarios where traditional OTP, push authentication, and even WebAuthn are not enough.

It is especially useful for:

offline authentication
legacy OTP input forms
QR-code and deep-link login
constrained hardware terminals
point-of-sale and IoT devices
transaction signing with human-visible confirmation
silent duress signaling
offline multi-device threshold approval

PPS is not trying to replace WebAuthn/FIDO2.

WebAuthn remains the preferred standard for browser-based passkey authentication.

PPS is designed to complement WebAuthn by covering operational gaps where WebAuthn is unavailable or impractical.

You can explore the protocol here:

Project website: https://pps-protocol.github.io
Specification: https://pps-protocol.github.io/pulseproof-sentinel/SPEC.html
Documentation: https://pps-protocol.github.io/pulseproof-sentinel/docs/
IETF Internet-Draft: https://datatracker.ietf.org/doc/draft-hezami-pulseproof-sentinel/
GitHub organization: https://github.com/pps-protocol

Why Not Just Use WebAuthn?

WebAuthn is excellent.

If you are building browser-based passwordless authentication, use WebAuthn.

But many real systems still need:

- OTP-style input fields
- offline verification
- hardware terminals without browser support
- transaction amount confirmation
- silent duress codes
- multi-device approval
- QR/deep-link authentication flows

That is where PPS fits.

Think of it like this:

Scenario	Recommended
Browser passkey login	WebAuthn/FIDO2
Legacy OTP form	PPS
Offline terminal authentication	PPS
High-value transaction signing	PPS
Silent duress authentication	PPS
Multi-device approval	PPS
IoT or constrained device authentication	PPS

Core Features

PPS includes a small core protocol plus optional advanced modules.

Core

Ed25519 signatures
deterministic CBOR encoding
time-bound Pulses
nonce binding
monotonic counter replay protection
relying-party binding
expiration enforcement

Optional Advanced Modules

forward-secure key ratcheting
silent duress / Honey-Pulse signaling
offline n-of-m threshold approval
transaction AmountMark verification
dynamic policy binding
environmental context binding

The protocol specification is available here:

https://pps-protocol.github.io/pulseproof-sentinel/SPEC.html

The PHP Implementation: `pps-php`

The core PHP implementation is available as a framework-agnostic package:

pps-protocol/pps-php

Links:

GitHub: https://github.com/pps-protocol/pps-php
Website: https://pps-protocol.github.io/pps-php/
Documentation: https://pps-protocol.github.io/pps-php/docs/
Packagist: https://packagist.org/packages/pps-protocol/pps-php

Install it with Composer:

composer require pps-protocol/pps-php

It supports:

Pulse creation
Pulse verification
registration flows
Trust Code generation
AmountMark transaction codes
duress keys
threshold signatures
offline mode
memory, file, PDO, and Redis storage backends

Quick Example: Creating a Pulse

Here is a simplified client-side example:

use Pps\Client\AuthenticatorClient;

$client = new AuthenticatorClient($clientState);

$pulse = $client
    ->rpId('example.com')
    ->nonce($nonceFromServer)
    ->createPulse();

echo $pulse['token'];
echo $pulse['trust_code'];

The server verifies the Pulse using only the stored public key.

No shared secret is required.

Laravel Integration: `laravel-pps`

If you are using Laravel, there is a dedicated integration package:

pps-protocol/laravel-pps

Links:

GitHub: https://github.com/pps-protocol/laravel-pps
Website: https://pps-protocol.github.io/laravel-pps/
Packagist: https://packagist.org/packages/pps-protocol/laravel-pps

Install it:

composer require pps-protocol/laravel-pps

Then run:

php artisan pps:install

This publishes the PPS config and migrations.

The package provides:

service provider
publishable configuration
API routes
HTTP controller
facade
Artisan commands
storage backend integration
transaction challenge endpoints
silent duress handling support

Default routes:

Method	Endpoint	Description
GET	`/pps/health`	Health check
GET	`/pps/challenge`	Create authentication challenge
POST	`/pps/register`	Register a device
POST	`/pps/verify`	Verify a Pulse Token
POST	`/pps/transaction/challenge`	Create transaction challenge
POST	`/pps/transaction/verify`	Verify transaction-bound Pulse

Test the health endpoint:

curl http://localhost:8000/pps/health

Example response:

{
    "status": "ok",
    "protocol": "PulseProof Sentinel Protocol",
    "version": 1,
    "algorithm": "PPS-ED25519-CBOR30",
    "epoch_seconds": 30,
    "rp_id": "localhost"
}

Transaction Signing With AmountMark

One of the most useful PPS features is transaction signing.

Imagine a withdrawal:

Amount: 2,500,067 IRR
Trust Code: 49371867

The last two digits, 67, are derived from the transaction amount.

This allows the user to visually confirm that the signed transaction matches the displayed amount.

The client binds the transaction hash and amount to the Pulse:

use Pps\Crypto\Base64Url;
use Pps\Payload\ContextObject;

$context = new ContextObject();
$context->sessionId = Base64Url::decode($sessionId);
$context->txHash = Base64Url::decode($txHash);

$pulse = $client
    ->rpId('example.com')
    ->nonce($nonce)
    ->context($context)
    ->amountMinor(2500067)
    ->createPulse();

The server verifies:

signature
nonce
counter
transaction hash
amount mark
Trust Code

This is much stronger than sending a plain OTP for transaction confirmation.

Silent Duress Authentication

PPS also supports silent duress signaling.

If a user is forced to authenticate, the client can sign with a hidden duress key.

The server detects this internally but returns a normal-looking success response.

if ($result->honey) {
    // Return normal response.
    // Internally restrict account, alert security, delay settlement, etc.
}

This is useful for fintech, banking, crypto exchanges, and high-risk accounts.

The outward response should remain indistinguishable from a normal login.

How PPS Compares to TOTP

Feature	TOTP	PPS
Shared secret on server	Yes	No
Asymmetric proof	No	Yes
Offline capable	Yes	Yes
Legacy OTP form support	Yes	Yes
Transaction binding	Weak	Strong
Amount confirmation	No	Yes
Silent duress	No	Optional
Threshold approval	No	Optional
Policy binding	No	Optional
Context binding	No	Optional

Important Links

Here are the most important links if you want to explore PPS:

Project website: https://pps-protocol.github.io
Protocol repository: https://github.com/pps-protocol/pulseproof-sentinel
Specification: https://pps-protocol.github.io/pulseproof-sentinel/SPEC.html
Documentation: https://pps-protocol.github.io/pulseproof-sentinel/docs/
IETF Internet-Draft: https://datatracker.ietf.org/doc/draft-hezami-pulseproof-sentinel/
PHP core package: https://github.com/pps-protocol/pps-php
PHP package docs: https://pps-protocol.github.io/pps-php/docs/
Laravel package: https://github.com/pps-protocol/laravel-pps
Laravel package website: https://pps-protocol.github.io/laravel-pps/
Packagist core package: https://packagist.org/packages/pps-protocol/pps-php
Packagist Laravel package: https://packagist.org/packages/pps-protocol/laravel-pps

Try It

If you are building:

fintech authentication
crypto withdrawal confirmation
offline device authentication
POS or IoT login
high-security admin approval
duress-aware accounts
multi-device authorization

PPS may be worth exploring.

Start with the website:

https://pps-protocol.github.io

Then read the specification:

https://pps-protocol.github.io/pulseproof-sentinel/SPEC.html

If you use PHP or Laravel, install the packages:

composer require pps-protocol/pps-php
composer require pps-protocol/laravel-pps

PPS is experimental, so it is not recommended for production without security review. But if you are interested in authentication protocols, asymmetric OTP alternatives, or transaction signing, it is definitely worth a look.

If you find the idea useful, star the repositories, test the packages, and share feedback.

GitHub organization:

https://github.com/pps-protocol

Master Role-Based Access Control with Laravel Permission Manager

Hossein Hezami — Wed, 24 Sep 2025 14:33:20 +0000

Building a secure, scalable Laravel application often requires a robust permission management system. Enter Laravel Permission Manager, a powerful package designed to streamline role-based access control (RBAC) with a flexible, feature-rich API. Whether you're securing routes, managing roles, or integrating permissions into your Blade templates, this package has you covered. In this post, I'll walk you through its installation, configuration, and usage to help you implement a bulletproof RBAC system in your Laravel app.

Why Laravel Permission Manager?

The Laravel Permission Manager package, developed by Hossein Hezami, offers a comprehensive solution for managing roles and permissions in Laravel applications. Here’s what makes it stand out:

Role-Based Access Control (RBAC): Assign multiple roles to users and permissions to roles.
Wildcard Permissions: Support for flexible route matching (e.g., admin.*, *admin*).
Blade Directives: Easily check roles and permissions in templates with @hasRole and @hasPermission.
Artisan Commands: Manage roles and permissions from the command line.
Facade Methods: Programmatically handle roles and permissions with a fluent API.
Middleware Support: Protect routes with role or permission checks.
Caching: Boost performance with permission caching.
Multi-Guard Support: Works seamlessly with Laravel’s authentication guards.
Export/Import: Save and restore roles/permissions as JSON.

Ready to get started? Let’s dive into the setup and usage.

Installation

Installing Laravel Permission Manager is straightforward with Composer. Follow these steps to integrate it into your Laravel project:

Install the Package Run the following command to install the package:

   composer require hosseinhezami/laravel-permission-manager

Register the Service Provider (Optional) If Laravel’s package auto-discovery is disabled, add the service provider and facade to config/app.php:

   'providers' => [
       // ...
       HosseinHezami\PermissionManager\PermissionManagerServiceProvider::class,
   ],
   'aliases' => [
       // ...
       'PermissionManager' => HosseinHezami\PermissionManager\Facades\PermissionManager::class,
   ],

Publish Configuration and Migrations Publish the configuration file and migrations to set up the package:

   php artisan vendor:publish --provider="HosseinHezami\PermissionManager\PermissionManagerServiceProvider" --tag="config"
   php artisan vendor:publish --provider="HosseinHezami\PermissionManager\PermissionManagerServiceProvider" --tag="migrations"

Run Migrations Create the necessary database tables for roles and permissions:

   php artisan migrate

Add the Permission Trait Add the PermissionTrait to your User model:

   namespace App\Models;

   use HosseinHezami\PermissionManager\Traits\PermissionTrait;
   use Illuminate\Foundation\Auth\User as Authenticatable;

   class User extends Authenticatable
   {
       use PermissionTrait;
   }

Run the Install Command For a streamlined setup, use the Artisan install command. Here are some variations:

   # Basic installation
   php artisan permission-manager:install

   # Install and run migrations
   php artisan permission-manager:install --migrate

   # Install, run migrations, and overwrite existing files
   php artisan permission-manager:install --migrate --force

   # Install with a custom User model path
   php artisan permission-manager:install --user-model=/path/to/User.php

Configuration

After publishing the configuration, you can customize the package in config/permission-manager.php. Here’s a sample configuration:

return [
    'models' => [
        'role' => \HosseinHezami\PermissionManager\Models\Role::class,
        'permission' => \HosseinHezami\PermissionManager\Models\Permission::class,
        'user' => \App\Models\User::class,
    ],
    'tables' => [
        'roles' => 'roles',
        'permissions' => 'permissions',
        'role_permissions' => 'role_permissions',
        'user_roles' => 'user_roles',
    ],
    'cache_duration' => 60, // Cache permissions for 60 minutes
    'log_denials' => false, // Log permission/role denials
    'wildcards' => true, // Enable wildcard support
];

This file lets you tweak model classes, table names, caching duration, and wildcard support to suit your application’s needs.

Database Migrations

The package creates four tables to manage roles and permissions:

roles: Stores role details (name, slug, description).
permissions: Stores permission routes (e.g., users.edit).
role_permissions: Links roles to permissions.
user_roles: Links users to roles.

The migrations are automatically published when you run the vendor:publish command for the migrations tag.

Usage

Let’s explore how to leverage Laravel Permission Manager in your application.

1. Blade Directives

Control access in your Blade templates with intuitive directives:

@hasRole('admin')
    <p>Welcome, Admin!</p>
@endhasRole

@hasPermission('users.edit')
    <a href="/users/edit">Edit User</a>
@endhasPermission

These directives make it easy to show or hide content based on roles or permissions.

2. Middleware

Protect routes with middleware for roles or permissions:

Route::get('/admin', [AdminController::class, 'index'])
    ->middleware('pm:role:admin|manager');

Route::get('/posts', [PostController::class, 'create'])
    ->middleware('pm:permission:posts|post.create');

The pm middleware ensures only users with the specified roles or permissions can access the route.

3. Artisan Commands

Manage roles and permissions directly from the terminal:

# List roles and permissions
php artisan roles:list
php artisan permissions:list

# Create a role
php artisan role:create admin "Administrator" "Has full system access"

# Update a role
php artisan role:update admin --name="Super Admin" --description="Updated description"

# Delete a role
php artisan role:delete admin

# Create permissions
php artisan permission:create "users.*"
php artisan permission:create "users.create,users.edit"

# Sync routes with permissions
php artisan permission:sync-routes

# Assign/revoke permissions to a role
php artisan role:assign-permission admin "users.*"
php artisan role:revoke-permission admin "users.edit"

# Assign/revoke roles to a user
php artisan user:assign-role 1 admin
php artisan user:revoke-role 1 admin

# Export/import roles
php artisan role:export roles.json
php artisan role:import roles.json

These commands make it easy to manage your RBAC system without writing code.

4. Facade Methods

For programmatic control, use the PermissionManager facade:

use HosseinHezami\PermissionManager\Facades\PermissionManager;

// Create a role
PermissionManager::roles()->create([
    'slug' => 'admin',
    'name' => 'Administrator',
    'description' => 'Has full system access'
]);

// Assign permissions to a role
PermissionManager::role('admin')->assignPermission('users.edit');

// Assign a role to a user
PermissionManager::user(1)->assignRole('admin');

// Check permissions
$hasPermission = PermissionManager::user(1)->hasPermission('users.edit');

5. Wildcard Permissions

Wildcard permissions add flexibility to route matching:

// Match all routes starting with 'admin'
PermissionManager::permissions()->create('admin.*');

// Match all routes containing 'admin'
PermissionManager::permissions()->create('*admin*');

6. Trait Methods

The PermissionTrait adds convenient methods to your User model:

$user = User::find(1);

// Assign a role
$user->assignRole('admin');

// Check permissions
if ($user->hasPermission('users.edit')) {
    // Allow edit action
}

Best Practices

Use Descriptive Slugs: Choose clear, meaningful slugs for roles and permissions (e.g., users.edit instead of edit).
Leverage Wildcards: Group related routes with wildcards (e.g., users.* for all user-related actions).
Sync Routes Regularly: Run php artisan permission:sync-routes to keep permissions aligned with your routes.
Enable Caching: Set a reasonable cache_duration in production to improve performance.
Handle Exceptions: Use the package’s custom exceptions (e.g., UnauthorizedException) for robust error handling.

Conclusion

The Laravel Permission Manager package is a game-changer for developers building secure Laravel applications. Its intuitive API, comprehensive Artisan commands, and flexible features like wildcard permissions and Blade directives make it a must-have for implementing RBAC. Whether you’re managing a small app or a large-scale system, this package simplifies access control without compromising on power.

Check out the official documentation for more details, and feel free to contribute via the GitHub repository. Got questions? Reach out to the maintainer at hossein.hezami@gmail.com.

What’s your favorite way to manage permissions in Laravel? Share your thoughts in the comments!

Build Laravel AI Features in Minutes: A Guide to the Gemini Package

Hossein Hezami — Fri, 12 Sep 2025 23:40:51 +0000

Tired of reading docs and just want to see the code? Let's dive straight into how you can use the hosseinhezami/laravel-gemini package to add powerful AI features to your Laravel application. The API is clean, fluent, and incredibly powerful.

Installation & Setup

First, get the package.

composer require hosseinhezami/laravel-gemini

Publish the config file and set your API key.

php artisan vendor:publish --tag=gemini-config

# .env
GEMINI_API_KEY=your_gemini_api_key_here

Code Examples: See It in Action

1. Basic Text Generation & Chat

The TextBuilder makes generating text or creating a chat interface simple.

use HosseinHezami\LaravelGemini\Facades\Gemini;

// Simple prompt
$response = Gemini::text()
    ->prompt('Write a tagline for a developer blog.')
    ->generate();

echo $response->content();

// Chat with history
$history = [
    ['role' => 'user', 'parts' => [['text' => 'Hello!']]],
    ['role' => 'model', 'parts' => [['text' => 'Hi there! How can I help?']]]
];

$response = Gemini::text()
    ->prompt('What’s the weather like?')
    ->history($history)
    ->temperature(0.7)
    ->generate();

echo $response->content();

2. Structured Data Extraction

Need consistent JSON output from a messy prompt? Use structuredSchema.

$response = Gemini::text()
    ->structuredSchema([
        'type' => 'object',
        'properties' => [
            'sentiment' => [
                'type' => 'string',
                'enum' => ['positive', 'negative', 'neutral']
            ],
            'confidence' => ['type' => 'number'],
            'key_points' => {
                'type' => 'array',
                'items' => {'type' => 'string'}
            }
        ],
        'required' => ['sentiment']
    ])
    ->prompt('The product is amazing but the delivery was late. I love the features though.')
    ->generate();

$analysis = json_decode($response->content());
// $analysis->sentiment, $analysis->key_points, etc.

3. Image Generation

Generate images from a text description.

$response = Gemini::image()
    ->prompt('A minimalist logo for a tech startup called "Nexus", using blue and green')
    ->generate();

// Save the generated image directly
$response->save(storage_path('app/logo.png'));

4. Document Understanding

Upload a file (PDF, DOC, image) and ask questions about it.

// First, upload the file to Gemini's servers
$fileUri = Gemini::files()->upload('document', $pathToInvoicePdf);

// Then, use it in a prompt
$response = Gemini::text()
    ->upload('document', $pathToInvoicePdf) // or use the $fileUri
    ->prompt('What is the total amount due on this invoice?')
    ->generate();

echo $response->content();

5. Text-to-Speech (Audio)

Generate spoken audio from text.

$response = Gemini::audio()
    ->prompt('Welcome to our application. We are thrilled to have you on board.')
    ->voiceName('Kore') // Check docs for available voices
    ->generate();

// The package smartly handles the binary response,
// allowing you to save it directly.
$response->save(public_path('audio/welcome.mp3'));

6. Real-Time Streaming

Crucial for building chat interfaces that feel fast and responsive.

// In your controller (e.g., app/Http/Controllers/ChatController.php)
public function stream(Request $request)
{
    return response()->stream(function () use ($request) {
        Gemini::text()
            ->model('gemini-2.5-flash-lite') // Use a fast model for streaming
            ->prompt($request->query('message'))
            ->stream(function ($chunk) {
                $text = $chunk['text'] ?? '';
                if (connection_aborted()) return;
                echo "data: " . json_encode(['text' => $text]) . "\n\n";
                ob_flush();
                flush();
            });
    }, 200, [
        'Content-Type' => 'text/event-stream',
        'Cache-Control' => 'no-cache',
        'Connection' => 'keep-alive',
        'X-Accel-Buffering' => 'no',
    ]);
}

Ready to Build?

This is just the surface. The package also handles video generation, embeddings, and full file management.

For complete documentation, check out the official docs:
https://hosseinhezami.github.io/laravel-gemini/

Source:

What will you build first? Let me know in the comments! 👇

DEV Community: Hossein Hezami

Fixing a Vue 3 Memory Leak in Large Lists: shallowRef and Virtualization

The Reactivity Bloat Trap

Diagnosing the Root Cause

Solving Deep Reactivity with shallowRef

Integrating Virtualization Correctly

Lifecycle Auditing and Component Cleanup

Production Verification

🚨 10 Authorization Anti-Patterns I Keep Finding in Laravel Apps (And the One-Line Fixes That Save Them)

📋 Table of Contents

🔁 The Pattern Behind the Patterns

🚫 Anti-Pattern #1: The if ($user->is_admin) Sprawl

The symptom

Why it breaks

The fix

🚫 Anti-Pattern #2: The God Role

The symptom

Why it breaks

The fix

🚫 Anti-Pattern #3: Role Explosion

The symptom

Why it breaks

The fix

🚫 Anti-Pattern #4: The Scattered Policy

The symptom

Why it breaks

The fix

🚫 Anti-Pattern #5: The Cache Trap

The symptom

Why it breaks

The fix

🚫 Anti-Pattern #6: The "Works on My Machine" Tenant

The symptom

Why it breaks

The fix

🚫 Anti-Pattern #7: The Silent Deny

The symptom

Why it breaks

The fix

🚫 Anti-Pattern #8: The Regex Wildcard Hell

The symptom

Why it breaks

The fix

🚫 Anti-Pattern #9: The Missing Audit Trail

The symptom

Why it breaks

The fix

🚫 Anti-Pattern #10: The 3 AM Debug Session

The symptom

Why it breaks

The fix

📦 One Package, Ten Fixes

📊 Comparison with Spatie

💭 Final Thoughts

The Laravel Authorization Cookbook: 12 Production-Ready Recipes for RBAC, ABAC, Teams & Deny Rules

📋 Table of Contents

🔪 Prep Your Kitchen (Installation)

🍳 Recipe 1: Classic RBAC with Wildcards

🍳 Recipe 2: The "One Exception" User

🍳 Recipe 3: The "Everything Except" Role

🍳 Recipe 4: Your Org Chart, as Code

🍳 Recipe 5: Owner-Only Editing (ABAC)

🍳 Recipe 6: Department-Scoped Approvals

🍳 Recipe 7: The Multi-Tenant Admin

🍳 Recipe 8: The 30-Day Contractor

🍳 Recipe 9: Bulletproof Route Protection

🍳 Recipe 10: Conditional UI Without the Mess

🍳 Recipe 11: The Compliance Trail

🍳 Recipe 12: The 2 AM Fix

🎁 Bonus Recipe: Testing Authorization

📊 Comparison with Spatie

💭 Final Thoughts

The 5 Levels of Laravel Authorization: From Basic RBAC to ABAC, Role Hierarchy & Multi-Tenancy (2026 Edition)

📋 Table of Contents

🤔 Why Authorization Has "Levels"

🥉 Level 1: Basic RBAC

Where Level 1 breaks

🥈 Level 2: Direct Permissions & Deny Rules

Direct Permissions (grant without a role)

Explicit Deny (the "except this one" rule)

🚫 Anti-Pattern #1: The `if ($user->is_admin)` Sprawl