README

Laravel Bitwise Permission

A fast, database-light permission system for Laravel.
Roles, permissions, routes and menus — resolved from a single integer, not a join table.

Documentation · Installation · Examples · Español

Why bitwise?

Most permission packages store one database row per role × permission × resource. That works, but it grows fast and every authorization check becomes a query — or a cache you have to invalidate correctly.

A bitwise permission is a single integer. Every capability is a power of two, so any combination of capabilities is just one number:

view (1) + create (4) + update (8) = 13

Checking access is a CPU-level AND operation, not a database lookup:

$access & $bit === $bit   // true or false, no query

Laravel Bitwise Permission builds a complete authorization layer on top of that idea — roles, per-route permissions, navigation menus, and an optional Livewire admin UI — while keeping the core check as cheap as it can possibly be.

Features

• 🔢 Bitwise core — combine and compare permissions with plain integer math, no runtime joins.
• 🧩 Route-based permissions — protect named routes with a wildcard convention (leads.*, deals.*).
• 🧭 Menus with role visibility — a self-managing navigation tree, including automatic parent/child propagation.
• 👑 Super admin bypass — a configured super admin role always has full access, without ever touching the database.
• 🧬 Per-user roles — RoleCloneService clones a base role per user, so individual permissions can diverge safely.
• 🖥️ Optional Livewire UI — manage roles, permissions, routes, accesses and menus from /bwp/* out of the box.
• ⚙️ Artisan tooling — bwp:install and bwp:sync-routes get a project wired up in minutes.
• 🧱 Config-first — bits, base permissions, roles, routes and menus are all defined in one published config file.

Quick look

use HenryHt\BitwisePermission\Traits\HasPermissionsTrait;

class User extends Authenticatable
{
    use HasPermissionsTrait;
}

Route::middleware('bwp.permission:create')->group(function () {
    Route::post('/leads', [LeadController::class, 'store'])->name('leads.store');
});

@if(auth()->user()->canCreate())
    <a href="{{ route('leads.create') }}">New lead</a>
@endif

@if(auth()->user()->isSuperAdmin())
    <span>Super Admin</span>
@endif

$user->setPermission('leads.*', 'modify access');
$user->setMenuAccess('leads', true);

Installation

composer require henry-ht/laravel-bitwise-permission
php artisan bwp:install

bwp:install publishes the config, migrations and assets, runs the migrations, and seeds the base roles, permissions and menus. See the installation guide for the manual, step-by-step version and for wiring up your User model.

Documentation

Full documentation, including configuration reference, middleware usage, role and permission management, menu building, and real-world examples, lives at bitwise.tchenry.com.

Requirements

• PHP 8.2+
• Laravel 11, 12 or 13
• Livewire 3 or 4 (only required if you use the bundled admin UI)

Testing

composer test

Changelog

Please see CHANGELOG.md for a history of releases.

Contributing

Contributions are welcome. Please read CONTRIBUTING.md before opening a pull request.

Security

If you discover a security vulnerability, please review SECURITY.md for our disclosure process — do not open a public issue.

Credits

• Henry HT
• All contributors

License

The MIT License (MIT). Please see LICENSE for more information.