Download the PHP package squareetlabs/laravel-simple-permissions without Composer

Squareetlabs/LaravelSimplePermissions

A comprehensive and flexible Laravel package for advanced permission management. This package provides a robust system for managing roles, permissions, groups, and entity-specific abilities.

Core Functionality:

• Role-Based Access Control (RBAC): Define custom roles with specific permission sets. Roles can be assigned to users to manage access levels efficiently.

• Permission System: Implement fine-grained permissions using a code-based system (e.g., posts.create, users.edit). Permissions are global entities that can be assigned to roles and groups. Supports wildcard permissions for flexible access patterns.

• Group Management (Optional): Organize users into groups. Groups can have their own permission sets, allowing for efficient permission management when multiple users need the same access level. This feature is optional and can be skipped if not needed.

• Entity-Specific Abilities: Grant or deny permissions for specific model instances (e.g., allowing a user to edit a particular post but not others). This provides the most granular level of access control.

• Caching & Performance: Intelligent caching system to optimize permission checks, reducing database queries and improving application performance.

• Audit Logging: Optional comprehensive audit trail that logs all permission-related actions including role assignments and permission changes.

• Laravel Integration: Seamlessly integrates with Laravel's built-in authorization system, including Policies, Blade directives, and middleware for route protection.

Key Features

• ✅ Roles & Permissions: Flexible role system with granular permissions
• ✅ Direct Permissions: Assign or revoke permissions directly to users, overriding role permissions
• ✅ Groups (Optional): Organize users into groups with shared permissions
• ✅ Abilities: (Optional) Entity-specific permissions for individual models
• ✅ Smart Caching: Caching system to optimize permission checks
• ✅ Audit Logging: Complete action logging (optional)
• ✅ Blade Directives: Blade directives for permission checks in views
• ✅ Policies: Integration with Laravel's Policy system
• ✅ Middleware: Middleware for route protection
• ✅ Artisan Commands: CLI tools for management
• ✅ Events: Event system for permission changes (RoleAssigned, RoleRemoved, AbilityGranted, AbilityRevoked, PermissionGranted, PermissionRevoked)
• ✅ Validation: Automatic validation of permission codes
• ✅ Performance: Optimized queries with eager loading

Requirements

• PHP >= 8.1
• Laravel 8.x, 9.x, 10.x, 11.x or 12.x

Installation

1. Install the Package

2. Publish Configuration and Migrations

This will publish:

• config/simple-permissions.php - Configuration file
• Database migrations

3. Configure the User Model

Add the HasPermissions trait to your User model:

4. Run Migrations

⚠️ IMPORTANT: Always do backups before running migrations.

[!NOTE] If you wish to use custom foreign keys and table names, modify config/simple-permissions.php before running migrations.

Optional Features Configuration

You can enable or disable optional features (Groups and Abilities) via configuration. When disabled, related migrations won't be published and related functionality will be skipped.

Configure in config/simple-permissions.php or via environment variables:

Or in config/simple-permissions.php:

[!NOTE] Important: Configure these settings before publishing migrations. If you disable a feature after migrations have been published, you'll need to manually remove the related migration files or tables.

Migrations:

• Essential: create_permissions_table.php, create_roles_table.php, create_role_user_table.php, create_permission_user_table.php, create_entity_permission_table.php
• Optional - Groups (create_groups_table.php, create_group_user_table.php): Only published if features.groups.enabled is true
• Optional - Abilities (create_abilities_table.php, create_entity_ability_table.php): Only published if features.abilities.enabled is true
• Optional - Audit Logging (create_audit_logs_table.php): Always published (table creation is handled by AuditService)

[!NOTE] The permission_user table is essential and always created. It allows direct permission assignments to users, overriding role-based permissions.

5. Optional Configuration

Enable Caching

To improve performance, enable caching in .env:

Enable Audit Logging

To log all permission actions:

Configuration

The configuration file config/simple-permissions.php contains all options:

Custom Models

Cache

Basic Usage

Creating Roles and Permissions

Assigning Roles to Users

Direct Permissions

You can assign or revoke permissions directly to users, overriding role-based permissions:

Priority Order:

1. Forbidden permissions (revoked via revokePermission()) have the highest priority
2. If a permission is explicitly forbidden, the user won't have it even if their role has it
3. If a permission is directly granted, the user will have it even if their role doesn't have it
4. If no direct assignment exists, role and group permissions apply

Understanding Forbidden Permissions

When you use revokePermission(), the permission is marked as forbidden in the database (permission_user.forbidden = true). This is different from simply removing a permission:

When to use each method:

Important: The allPermissions() method automatically filters out forbidden permissions, ensuring consistency between permission checks and permission lists.

Checking Permissions

Users

The HasPermissions trait provides the following methods:

Roles & Permissions

Wildcard Permissions

You can use wildcards for permissions:

• posts.* - All permissions starting with posts.
• * - All permissions (if enabled in config)

Checking Permissions

Abilities

[!NOTE] Abilities are optional. Enable/disable via SIMPLE_PERMISSIONS_ABILITIES_ENABLED in your .env file or config/simple-permissions.php. When disabled, ability-related migrations won't be published. The hasAbility() method will fall back to checking global permissions, and methods like allowAbility(), forbidAbility(), and removeAbility() will throw an exception.

Abilities allow specific permissions for individual entities.

Creating and Assigning Abilities

You can use helper methods for easier ability management:

Or use the direct approach:

Checking an Ability

Groups

[!NOTE] Groups are optional. Enable/disable via SIMPLE_PERMISSIONS_GROUPS_ENABLED in your .env file or config/simple-permissions.php. When disabled, group-related migrations won't be published and group functionality will be skipped automatically.

Groups allow organizing users with shared permissions. This is useful when multiple users need the same set of permissions and you want to manage them collectively.

Creating and Managing Groups

Middleware

The package provides middleware for route protection.

Usage in Routes

OR Operations

Blade Directives

The package includes Blade directives for permission checks in views:

Policies

The package integrates with Laravel's Policy system.

Generate a Policy

Using the Policy

Events

The package dispatches events when permissions change, allowing you to hook into these actions:

Available Events

• RoleAssigned: Dispatched when a role is assigned to a user
• RoleRemoved: Dispatched when a role is removed from a user
• PermissionGranted: Dispatched when a permission is granted directly to a user
• PermissionRevoked: Dispatched when a permission is revoked directly from a user
• AbilityGranted: Dispatched when an ability is granted to a user
• AbilityRevoked: Dispatched when an ability is revoked from a user

Listening to Events

Example Listener

Artisan Commands

The package includes several useful commands:

Management