Download the PHP package happenv-com/laravel-access-control without Composer

Laravel Access Control

A modular access control library for Laravel applications that uses enum-based permissions and a voter system. Perfect for modular monolith architectures where different modules can define their own permission logic and extend existing.

Example

Imagine two modules: Product and ProductGallery. The Product module knows nothing about ProductGallery, but ProductGallery should block product deletion until all galleries are removed.

Product module defines the permission:

ProductGallery module registers a voter to add its constraint:

This library allows achieving such behavior without tightly coupling the two modules.

Key Features

• 🔐 Enum-based permissions - Define permissions as PHP enums for type-safety and IDE autocomplete
• 🗳️ Voter system - Replace Laravel Policies with flexible voters that can be registered from any module
• 📦 Modular architecture - Each module can register its own voters without modifying core logic
• 🏷️ Permission metadata - Add names, descriptions, and groups to permissions via PHP attributes
• ⚡ Laravel Gate integration - Works seamlessly with Laravel's authorization system

When to Use This Package

This package is designed primarily for modular monolith architectures where your application is split into independent modules (e.g., using nWidart/laravel-modules or InterNACHI/modular).

The key advantage of this package is that voters can be registered from any module, allowing each module to define its own authorization constraints without modifying the core application or other modules.

When NOT to Use This Package

If you're building a traditional Laravel monolith without modular architecture, you probably don't need this package. In that case, the following solutions are sufficient:

• Laravel Policies - Built-in authorization system, perfect for simple applications
• spatie/laravel-permission - Excellent package for role and permission management in monolithic applications

Requirements

• PHP 8.4+
• Laravel 12.0+

Installation

You can install the package via composer:

Usage

1. Define Permissions as Enums

Create an enum that implements PermissionDefinition:

Tip: In modular applications, consider prefixing permission values with your module name (e.g., pim-module.product.view, inventory-module.stock.update) to avoid conflicts between modules and make it clear which module owns each permission.

2. Register Permissions

Register your permission enums in a service provider:

3. Register Voters

Voters allow you to add custom authorization logic to permissions. The main advantage is that voters can be registered from any module, making them perfect for modular monolith architectures.

Using Closures

Using Voter Classes

For more complex logic, create dedicated voter classes with the #[VoterForPermission] attribute:

Register the voter class:

4. Using Authorization

The package integrates with Laravel's Gate, so you can use standard authorization methods:

5. Adding Permission Metadata (Optional)

Enhance your permissions with names, descriptions, and groups using PHP attributes:

Permission Groups

First, create a permission group:

Enhanced Permission Enum

Retrieving Permission Metadata

This is useful for building permission management UIs.

How Voters Work

1. When a permission check is performed via Laravel's Gate, the package first verifies if the user has the permission (via $user->hasPermissionTo())
2. If the user has the permission, all registered voters for that permission are executed
3. If any voter returns Response::deny(), the authorization fails
4. Only if all voters return Response::allow(), the authorization succeeds

This allows different modules to add constraints to permissions without knowing about each other.

Voters vs Policies

Model Setup

The model on which authorization checks are performed (typically User) must implement the AuthControllable interface.

This package provides three traits for managing permissions:

HasRoles (Recommended)

Use this trait when users receive permissions only through roles. This is the recommended approach for most applications.

HasPermissions

Use this trait for models that store permissions directly (e.g., a Role model). This trait provides givePermissionTo() and revokePermissionTo() methods.

You can also use this trait directly on User.

HasRolesAndPermissions

Use this trait when users can receive permissions both through roles AND directly. Permissions are checked in both sources.

Testing

License

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