Download the PHP package scabarcas/laravel-permissions-redis without Composer

Laravel Permissions Redis

A Redis-backed roles and permissions package for Laravel with a Spatie-compatible API. It keeps each user's resolved permissions in Redis and invalidates the cache surgically (one user at a time) instead of flushing everything on every change.

Inspired by spatie/laravel-permission, the de facto standard for roles and permissions in Laravel. This package keeps its familiar API (hasRole, hasPermissionTo, assignRole, Blade directives, middleware) but changes the storage layer: Spatie caches the permission registry yet still lazy-loads each user's role and permission relations from the database per request (about 4 queries), while this package keeps the resolved per-user set in Redis (1 query). The goal is to take authorization load off the database and avoid full cache-flush stampedes on permission changes, not to be dramatically faster. For most apps, Spatie with its cache is simpler and enough; this package earns its place when the database is your bottleneck or permissions change often at scale.

Table of Contents

• Requirements
• Architecture
• Installation
• Configuration
• Usage Guide
  • Setting Up the User Model
  • Creating Roles and Permissions
  • Assigning Roles and Permissions
  • Checking Roles and Permissions
  • Middleware
  • Blade Directives
  • Gate Integration
  • Wildcard Permissions
  • Super Admin
  • Cache Management
• UUID / ULID Support
• Laravel Octane
• Multi-Tenancy
• Integrations
• Conventions
• API Reference
• Testing
• Comparison with spatie/laravel-permission
  • Feature Comparison
  • Performance Benchmark
  • When to Use This Package
• Migrating from Spatie
• Troubleshooting
• Versioning
• License

Requirements

Runtime

Laravel 11 note: the composer constraint allows Laravel 11, but CI only exercises Laravel 12 and 13 (the Pest 4 test harness requires testbench 10+, which starts at Laravel 12). Laravel 11 reached end of life in March 2026, so support is best-effort on the 4.x line and the constraint will be dropped in v5.

PHP Extensions

The redis extension (phpredis) is recommended in production (pecl install redis). If you can't install it, predis/predis works as a userland alternative: set 'client' => 'predis' in config/database.php under the Redis section.

Laravel Components Used

Development Dependencies

Infrastructure

Architecture

Note: The diagrams below use Mermaid. If they appear as code blocks, view them rendered on GitHub.

System Context

Container Diagram

Resolution Flow

Cache Invalidation Flow

Redis Key Structure

Installation

Requirements

• PHP 8.3+
• Laravel 11, 12, or 13
• Redis extension (phpredis or predis)

Step 1: Install via Composer

The service provider is auto-discovered. No manual registration needed.

Step 2: Publish Assets

Publish config and migrations together:

Or publish individually by tag:

Step 3: Run Migrations

Creates 5 tables: permissions, roles, model_has_permissions, model_has_roles, role_has_permissions.

Step 4: Configure Redis

Ensure your config/database.php has a working Redis connection. The package uses 'default' by default:

Step 5: Warm the Cache

This loads all existing permissions and roles into Redis. Run this after initial setup or after direct database modifications.

Configuration

All options live in config/permissions-redis.php:

Usage Guide

Setting Up the User Model

Add the HasRedisPermissions trait to your User model:

Multiple User Models

If your application authorizes more than one Eloquent model (e.g., User for the web app and Admin for the back office), configure an array of FQCNs:

AuthorizationCacheManager iterates all configured types when resolving role/permission assignments, and the Gate::before callback accepts all of them. Each model still needs the HasRedisPermissions trait.

Creating Roles and Permissions

Use the findOrCreate static method on both models:

Assigning Roles and Permissions

All assignment methods accept: string, int (ID), BackedEnum, array, or Collection.

Checking Roles and Permissions

Query Scopes

Scopes run SQL, not Redis. scopeRole and scopePermission issue database queries against the pivot tables and do not consult the Redis cache. Use them for reporting, admin dashboards, or any context where you need the full user list, not in hot authorization paths (hasPermissionTo, middleware, Blade). For a throughput-sensitive "which users have role X" lookup, call $cacheManager->getUserIdsAffectedByPermission($name) or the equivalent role-cache method, both of which read from Redis.

Middleware

The package registers three middleware aliases automatically:

permission: Require permissions

role: Require roles

role_or_permission: Require role OR permission

Operators: | = OR (any), & = AND (all).

Blade Directives

Every directive also has an unless variant (@unlessrole, @unlesspermission, @unlesshasanyrole, ...) that renders when the check fails. They close with the regular @endrole / @endpermission tags, not @endunlessrole.

Guard Override

All six directives accept an optional second argument to scope the check to a specific guard (defaults to the current authentication driver):

This is especially useful in SPA or API-token contexts where the active web session differs from the guard you want to authorize against.

Gate Integration

When register_gate is enabled (default), Laravel's Gate resolves permissions through Redis:

Wildcard Permissions

Enable in config or .env:

Then assign wildcard permissions:

Uses PHP's fnmatch(), which supports *, ?, and [...] patterns.

Super Admin

Set a super admin role in config or .env:

Cache Management

Artisan Commands

The package also registers a section in php artisan about with the installed version, Redis connection, key prefix, TTL, and whether tenancy, wildcards, and the super admin role are enabled.

Both warm commands accept --queue to push the operation onto the queue instead of running it synchronously. This is the recommended approach for large user tables or post-deploy rewarms:

Under the hood this dispatches WarmUserCacheJob per user; the job is idempotent and safe to retry.

Programmatic Access

Automatic Invalidation

The cache is automatically invalidated when:

To auto-dispatch UserDeleted, add the trait to your User model:

Rate-limited cache-miss warming

When a permission check lands on a user whose cache is missing in Redis, PermissionResolver triggers warmUser() automatically. To protect the database from warm storms (e.g., Redis is cold after a restart and thousands of simultaneous requests hit the same user), the resolver records each warm attempt and suppresses retries for resolver_warm_cooldown seconds (default 1.0s). This is in-memory per worker; tune it via config or the PERMISSIONS_REDIS_WARM_COOLDOWN env variable.

Multi-tenant deployments

When TenantAwareRedisPermissionRepository is registered, all user and role cache keys are prefixed with the current tenant ID (t:{id}:*). Permission group metadata is intentionally stored globally (un-prefixed) because permission definitions live in the shared permissions table and are not tenant-specific.

Database Seeding

Define your roles and permissions in config/permissions-redis.php and seed them with a single command:

The command creates all permissions referenced under roles automatically. Existing permissions and roles are left unchanged in incremental mode (default). The --fresh flag deletes all existing permissions, roles, and pivot assignments before seeding.

UUID / ULID Support

This package supports integer, UUID, and ULID primary keys for your User model. Set the column type in your configuration before running migrations:

All APIs (hasPermissionTo, assignRole, middleware, Blade directives, etc.) work transparently with any ID type. No code changes required beyond the config setting.

Note: If you have already run migrations with 'int' and need to switch to UUID/ULID, you will need to create a new migration to alter the model_id columns in the pivot tables.

Laravel Octane

When running under Laravel Octane, singletons persist across requests. This package provides built-in support to flush in-memory caches between requests, preventing stale permission data from leaking.

Setup

Or in your config:

When enabled, the package listens to RequestReceived and automatically:

1. Flushes the PermissionResolver in-memory caches (permission, role, super admin)
2. Resets the RedisPermissionRepository cached connection, prefix, and TTL

This ensures each Octane request starts with a clean state while still benefiting from Redis-level caching.

Multi-Tenancy

The package supports multi-tenant applications by prefixing Redis keys with a tenant identifier, ensuring complete isolation of permission data between tenants.

Setup

Or in your config:

Built-in Resolvers

Custom Resolver

Create a class that returns the current tenant identifier:

How It Works

When tenancy is enabled, user-related Redis keys are prefixed with the tenant ID:

Role-related keys are prefixed the same way (auth:role:t:acme:5:permissions), so cached role data is isolated per tenant even though role definitions live in the shared database tables.

Integrations

This package works well with Laravel Policies, Sanctum/Passport, and Pulse. See the full integrations guide for detailed examples.

Laravel Policies

Policies work automatically with this package. The Gate before callback checks Redis first. If the user has the permission, it's granted immediately. If not, the Policy method decides:

Laravel Sanctum / Passport

Combine token abilities with Redis permissions for API routes:

For dual enforcement (token ability + user permission), see the custom middleware example in the integrations guide.

Laravel Pulse

Track permission check performance with a custom Pulse recorder. The integrations guide includes a complete setup with recorder, decorator, and dashboard card. No Pulse dependency is required in this package.

Conventions

Permission Naming

Use dot notation with the pattern resource.action:

Permission Groups

Group related permissions for organizational clarity:

Role Naming

Use lowercase snake_case:

Guard Names

Permissions and roles are scoped by guard. The default is 'web'. If you use multiple guards (e.g., api), specify the guard explicitly:

Fluent Guard Scoping

Use forGuard() to scope a single check without passing the guard to every method:

Enum Support

You can use BackedEnum for type-safe permission/role references:

Direct vs. Role-Based Permissions

• Role-based (recommended for most cases): Assign permissions to roles, assign roles to users. Changes to a role affect all users with that role.
• Direct. Assign permissions directly to a user for exceptions or overrides. Direct permissions are merged with role-inherited permissions.

Permission checks always see the merged set. When business logic needs to distinguish the two sources at runtime, use getDirectPermissions() / getPermissionsViaRoles(); both read the Eloquent relations (SQL), not the Redis cache.

API Reference

HasRedisPermissions Trait: Check Methods

HasRedisPermissions Trait: Retrieval Methods

HasRedisPermissions Trait: Assignment Methods

All assignment methods accept: string, int (ID), BackedEnum, array, or Collection.

HasRedisPermissions Trait: Relationships & Scopes

Role Model Methods

Deleting a role dispatches RoleDeleted and automatically rewarms affected users' caches.

Permission Model Methods

Updating or deleting a permission automatically rewarms all affected users' caches.

AuthorizationCacheManager

Exceptions

All exceptions extend Symfony\Component\HttpKernel\Exception\HttpException. Use getRequiredItems() to retrieve the missing roles/permissions:

Events

All events are in the Scabarcas\LaravelPermissionsRedis\Events namespace and use the Dispatchable trait.

Artisan Commands

Testing

The package uses Pest for testing and provides an InMemoryPermissionRepository for testing without Redis:

Testing in Your Application

WithPermissions Trait

The package provides a WithPermissions trait with helpers for feature tests:

Available methods:

Pest Example

InMemoryPermissionRepository

Alternatively, bind the in-memory repository in your test suite to avoid Redis entirely:

Comparison with spatie/laravel-permission

Feature Comparison

Performance Benchmark

A standalone benchmark application compares both packages side by side, run with php artisan bench:markdown 1,10,50 --warm=5 --runs=30 (Apple Silicon, PHP 8.x, predis, local Redis). Each "request" resets in-memory state, so neither package carries PHP process memory across requests (matching PHP-FPM, and Octane where this package resets its in-memory cache per request). The hardware-independent result is the query count (4 queries hitting several tables versus 1). Wall-clock is modest and depends heavily on your database, so read the latency tables with that in mind.

Database queries per authorization-heavy request

Spatie caches the global permission/role registry, but each User::find() still lazy-loads that user's role and permission relations from the database (about 4 queries across several tables). This package keeps the resolved per-user set in Redis, so the only database query left is the SELECT ... FROM users lookup; the rest is served from Redis plus a per-request in-memory cache.

Wall-clock per request (median, p50)

On in-process SQLite (database queries are nearly free, which isolates the Redis/in-memory paths):

On MySQL over TCP (a realistic networked database; numbers are noisy across runs):

Each request exercises 27 hasPermissionTo calls, 4 hasRole calls, 4 batch ops, and 2 collection calls. On SQLite, avoiding 3 relation queries shows up as ~1.4x. On a networked database this package replaces those DB queries with several Redis reads (SMEMBERS / HMGET) over the same network, so latency lands close to Spatie plus cache and the edge is small and noisy (clear only on authorization-heavy requests). It was never the order of magnitude older numbers implied. The durable, hardware-independent difference is the query count above; the latency benefit is real but modest and database-dependent.

How the two approaches differ

Where it actually helps

• Reducing database load. The durable win is 75% fewer DB queries per request (across several tables), which shifts authorization reads off the database and its connection pool onto Redis. It also gives a modest latency win, larger on slower or more remote databases.
• Frequent role/permission changes. Spatie drops the whole registry cache on any change; this package rewarms only the affected user(s), avoiding a cache-rebuild stampede.
• Multi-tenant apps. Per-tenant Redis key isolation is built in.

If your app runs a handful of checks per request at low traffic, Spatie with its cache is perfectly adequate and simpler (no hard Redis dependency). See When to Use This Package.

Try it yourself

See the benchmark repository for full details, screenshots, and instructions.

When to Use This Package

Use laravel-permissions-redis when:

• Database load is your bottleneck. You want authorization reads off the database and its connection pool: 1 query per request instead of 4. Per-request latency improves modestly too (more on slow or remote databases), but this is not an order-of-magnitude speedup.
• You already run Redis. If Redis is part of your stack (sessions, queues, cache), adding authorization to it is a natural fit with no additional infrastructure.
• You use Laravel Octane. Built-in support for flushing in-memory state between requests prevents stale permission data in long-lived workers.
• You need multi-tenancy. Redis key isolation per tenant is built in, with support for stancl/tenancy or custom resolvers.
• You want always-warm cache. Instead of "forget and reload", this package keeps the cache hot with surgical invalidation.
• You want wildcard permissions. fnmatch() patterns like posts.* are fully supported.
• You want a super admin role. One config option bypasses all permission checks for a designated role.

Stick with spatie/laravel-permission when:

• You don't run Redis. This package requires Redis. If your infrastructure doesn't include it and you don't want to add it, Spatie works with any Laravel cache driver.
• You need the teams feature. Spatie's teams support is more mature than this package's multi-tenancy for certain team-based authorization patterns.
• You support older PHP/Laravel versions. Spatie supports PHP 8.0+ and Laravel 8+. This package requires PHP 8.3+ and Laravel 11+.
• Authorization is not a bottleneck. If your app has low traffic and few permission checks per request, the database-backed approach is perfectly adequate.

Migrating from Spatie

Coming from spatie/laravel-permission? The API is intentionally similar. Most changes are namespace swaps and config adjustments.

See the full migration guide for:

• Step-by-step migration instructions
• Method equivalence table (Spatie to this package)
• Behavior differences to be aware of
• Config mapping between both packages
• Artisan command to copy data and warm cache: permissions-redis:migrate-from-spatie

Troubleshooting

Redis connection refused

Symptom: ConnectionException: Connection refused or Redis server went away.

Fix:

1. Verify Redis is running:

2. Check your .env Redis settings:

3. Verify the connection name in config/permissions-redis.php matches a connection defined in config/database.php:

4. If using Docker, ensure the Redis service is accessible from your app container (use the service name, not 127.0.0.1).

Cache not invalidating after changes

Symptom: assignRole() or givePermissionTo() succeeds but hasRole() / hasPermissionTo() still returns the old value.

Fix:

1. Verify the event subscriber is registered. The CacheInvalidator subscriber should be active:

2. Check that you are not suppressing events. Model::withoutEvents() or Event::fake() will prevent cache invalidation:

3. If you modify pivot tables directly via DB::table(), the cache won't auto-update. Warm manually:

4. For Octane users, ensure reset_on_request is enabled so in-memory caches don't persist across requests:

Permissions not detected after assignment

Symptom: $user->hasPermissionTo('posts.edit') returns false even though the permission was just assigned.

Fix:

1. Guard mismatch (the most common cause): Permissions and roles are scoped by guard name. If a permission was created with guard web but you're checking from an api guard context, it won't match:

2. Permission not assigned to role. If the user has a role but the role doesn't have the permission:

3. Cache is stale. Force a cache refresh:

Performance degradation

Symptom: Permission checks are slower than expected.

Diagnose:

1. Check cache statistics:

   • 0 cached users = cache is cold. Run php artisan permissions-redis:warm.
   • TTL too low = cache expires too often. Increase PERMISSIONS_REDIS_TTL.

2. Check Redis latency:

   Latency above 1ms may indicate network issues between app and Redis.

3. If using predis (userland PHP client), consider switching to phpredis (C extension) for better performance:

   Then set 'client' => 'phpredis' in config/database.php.

4. If wildcard permissions are enabled and you have many permissions per user, fnmatch() scans all permissions. Consider using explicit permissions instead of wildcards for hot paths.

Conflict with spatie/laravel-permission

Symptom: Unexpected behavior when both packages are installed, or errors after removing Spatie.

Fix:

1. Both installed (during migration): Both packages register the same middleware aliases (permission, role, role_or_permission). Whichever service provider loads last wins. This is expected during migration. Follow the migration guide.

2. After removing Spatie:

3. Remove Spatie's config if it still exists:

4. Search for leftover Spatie references:

Migrations not publishing

Symptom: vendor:publish doesn't create migration files or config.

Fix:

1. Verify the package is installed:

2. Verify service provider auto-discovery is working:

3. Publish by tag explicitly:

4. If using dont-discover in composer.json, register the service provider manually in bootstrap/providers.php:

Versioning

This package follows Semantic Versioning. The early 1.x through 4.x line moved fast and shipped breaking changes more often than it should have; from 4.x onward the API is considered stable, and breaking changes will only land in a new major (5.0.0). Minor releases add backwards-compatible features, patch releases are fixes only. If a release breaks something that this policy says it shouldn't, please open an issue, it's a bug.

License

This package is open-sourced software licensed under the MIT License.

Acknowledgements

This package is heavily inspired by spatie/laravel-permission by Spatie. Their work established the conventions and API patterns that the Laravel community knows and trusts. This package builds on those foundations, re-engineering the storage and resolution layer to use Redis as the primary cache with automatic invalidation.

Key concepts inherited from Spatie:

• The HasRoles / HasPermissions trait pattern for the User model
• findOrCreate semantics for roles and permissions
• Guard-scoped permissions and roles
• Blade directives (@role, @permission, @hasanyrole, etc.)
• Route middleware (permission, role, role_or_permission)
• Direct permissions vs. role-based permissions

Author

Sebastian Cabarcas | [email protected]