Download the PHP package techieni3/laravel-user-permissions without Composer

Laravel User Permissions

A Laravel package for managing user roles and permissions. It uses PHP enums for type-safe role definitions and provides a web dashboard for managing access control. Ideally suited for applications that require a robust, easy-to-manage permission system with a visual interface.

Table of Contents

• Requirements
• Installation
• Quick Start
• Configuration
• Dashboard
• Working with Roles
• Working with Permissions
• Laravel Gate Integration
• Middleware
• Model Actions
• Cascade Deletion
• Events
• Model Discovery Configuration
• Caching
• Testing
• Similar Packages
• Security
• License

Requirements

• PHP 8.4+
• Laravel 12.35.0+

Installation

Install the package via Composer:

Run the installation command to set up the package:

This command will:

• Publish the config file to config/permissions.php
• Publish migrations to database/migrations/
• Publish Role.php ModelActions.php enums to app/Enums
• Add the HasRoles trait to your User model

Run the migrations:

Quick Start

1. Define Your Roles

Edit app/Enums/Role.php:

2. Sync Roles to Database

3. Generate Permissions

The package automatically generates permissions for your models based on actions defined in app/Enums/ModelActions.php:

This creates permissions like post.create, post.update, user.view_any, etc.

4. Assign Roles and Permissions

Configuration

The config file is located at config/permissions.php:

Dashboard Configuration

enabled - Enable or disable the web dashboard (default: true)

prefix - URL path for the dashboard (default: permissions-manager)

middleware - Middleware applied to dashboard routes (default: ['web', 'auth'])

gate - Gate name for authorizing dashboard access (default: viewPermissionsDashboard). Set to null to disable authorization.

user_display_column - Database column to display as username in the dashboard (default: name)

Model Discovery

included - Array of directory paths and/or specific model classes to include for permission generation. Can contain:

• Directory paths (e.g., app_path('Models')) - scans all models in the directory
• Specific model class strings (e.g., App\External\CustomModel::class) - includes individual models

excluded - Array of model classes to skip during permission generation

Core Classes

user - Your application's User model class

role_enum - The enum class defining your roles

model_actions_enum - The enum class defining permission actions

Events

events_enabled - Enable or disable event dispatching when roles/permissions change (default: true)

Dashboard

Access the dashboard at /permissions-manager (or your configured prefix).

Protecting Dashboard Access

Define a gate in your AppServiceProvider:

To disable gate authorization, set 'gate' => null in the config.

Dashboard Features

• Users Page: List all users, search, and view their roles/permissions
• Roles Page: List all roles and their assigned permissions
• User Detail: Assign/remove roles and permissions for a specific user
• Role Detail: Manage which permissions are assigned to a role

Screenshots

Users Access Management

Role Permissions

Dashboard Troubleshooting

Dashboard 404 Not Found

If you are unable to access the dashboard at /permissions-manager:

1. Ensure you have run php artisan migrate.
2. Clear your route cache: php artisan route:clear.
3. Verify the prefix in config/permissions.php.
4. Make sure a login route exists, as the dashboard is protected by the auth middleware by default.

Dashboard 500 Error

If you encounter a 500 Internal Server Error when accessing the dashboard:

1. Check that the viewPermissionsDashboard gate is defined in your AppServiceProvider (or use the custom gate name from your config).
2. Alternatively, set 'gate' => null in config/permissions.php to disable gate authorization.
3. Check your Laravel logs at storage/logs/laravel.log for specific error details.

Assets Not Loading

The dashboard uses inline styles and scripts. You do not need to publish assets. If the dashboard is blank:

1. Check your browser console for JavaScript errors.
2. Ensure APP_URL in your .env file is set correctly.

Working with Roles

Adding Roles

Removing Roles

Checking Roles

Query Users by Role

Working with Permissions

Adding Permissions

Removing Permissions

Checking Permissions

Query Users by Permission

Understanding Direct vs Role Permissions

Users can have permissions in two ways:

1. Direct permissions: Assigned directly to the user
2. Role permissions: Inherited from assigned roles

Laravel Gate Integration

All permissions are automatically registered with Laravel's authorization system:

Middleware

The package provides middleware for protecting routes.

Permission Middleware

Role Middleware

Role or Permission Middleware

Model Actions

The ModelActions enum defines which actions to generate permissions for:

You can add custom actions:

Run php artisan sync:permissions after modifying the enum.

Cascade Deletion

By default, when a user is deleted, their role and permission assignments remain in the database. To automatically clean up these relationships, use the CascadeDeletesRolesAndPermissions trait.

Setup

Add the trait to your User model alongside HasRoles:

How It Works

When a user is deleted, the trait will:

• Detach all assigned roles
• Detach all direct permissions
• Dispatch a RolesAndPermissionsDeleted event (if events are enabled)

The trait automatically detects if your model uses soft deletes:

• Hard deletes: Triggers on deleting event
• Soft deletes: Triggers on forceDeleting event (permanent deletion only)

Important Notes

Bulk Deletes: The trait only works for individual model deletions:

For bulk deletes, use this pattern instead:

Cleaning Up Orphaned Records

If you have orphaned pivot table records (from bulk deletes, database migrations, or other operations that bypass Eloquent events), use the cleanup command:

This command will:

• Remove users_roles records where the user or role no longer exists
• Remove users_permissions records where the user or permission no longer exists
• Remove roles_permissions records where the role or permission no longer exists

Scheduling Periodic Cleanup: Add to your app/Console/Kernel.php to run automatically:

Note: This cleanup command is particularly useful if you are using bulk delete operations

Events

The package dispatches events when roles and permissions change, allowing you to react to authorization changes in your application.

Available Events

Listening to Events

Event Properties

Individual Events (RoleAdded, RoleRemoved, PermissionAdded, PermissionRemoved):

• $model - The user model
• $role or $permission - The role/permission that was added or removed

Sync Events (RolesSynced, PermissionsSynced):

• $model - The user model
• $synced - Collection of roles/permissions after sync
• $previous - Collection of roles/permissions before sync
• $attached - Collection of roles/permissions that were added
• $detached - Collection of roles/permissions that were removed

Cascade Deletion Event (RolesAndPermissionsDeleted):

• $model - The user model being deleted
• $roles - Collection of roles that were detached
• $permissions - Collection of direct permissions that were detached

Disabling Events

Disable events by setting events_enabled to false in config or via environment variable:

Model Discovery Configuration

The package provides flexible options for discovering models to generate permissions.

Including Models and Directories

Specify which models to include using the included array. You can mix directory paths and specific model classes:

Excluding Models

To prevent specific models from having permissions generated, use the excluded array. This filters out models discovered from directories in the included array:

Caching

The package uses request-level caching for performance. Permissions and roles are cached during a single request and automatically cleared when changes occur.

You don't need to manually clear caches - the package handles this for you.

Testing

Run the test suite:

Run static analysis:

Format code:

Similar Packages

If this package doesn't fit your needs, check out these alternatives:

• spatie/laravel-permission - The most popular Laravel permissions package with teams support and blade directives
• JosephSilber/bouncer - Flexible roles and abilities with a focus on simplicity and model-level permissions

Credits

Images are generated by Gemini and Nono Banana.

Security

If you discover a security issue, please email [email protected] instead of using the issue tracker.

License

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