Laravel Permissions Manager Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require act-training/laravel-permissions-manager
   php artisan vendor:publish --tag=permissions-manager-config
   php artisan vendor:publish --tag=permissions-manager-migrations
   php artisan migrate
   

   • Verify config/permissions-manager.php exists and adjust settings if needed (e.g., protected_roles).

2. First Use Case:

   • Access the UI via /permissions-manager (or your configured route).
   • Permissions: Navigate to the "Permissions" tab to create/edit permissions with categories (e.g., admin, content) and descriptions.
   • Roles: Use the "Roles" tab to assign permissions to roles (e.g., Editor, Admin). Mark roles as "protected" to prevent deletion if users are assigned.
   • Users: Assign roles to users via the "Users" tab (integrates with Spatie’s hasRole()).

3. Quick Start with Code:

   use ACTTraining\PermissionsManager\Facades\PermissionsManager;
   
   // Create a permission
   PermissionsManager::createPermission('edit_posts', 'content', 'Can edit blog posts');
   
   // Assign to a role
   $role = PermissionsManager::findRole('Editor');
   $role->givePermissionTo('edit_posts');
   
   // Check user permissions
   if (auth()->user()->hasPermissionTo('edit_posts')) { ... }
   

Implementation Patterns

Core Workflows

1. Permission Management:

   • Bulk Actions: Use FluxUI’s table builder to select multiple permissions and assign them to a role via the "Bulk Assign" button.
   • Categories: Organize permissions by category (e.g., auth, reports). Categories appear as color-coded badges in the UI.
   • Descriptions: Add human-readable descriptions to permissions for clarity in the UI.

2. Role Management:

   • Protected Roles: Roles with users assigned cannot be deleted unless unassigned first. Configure protected roles in config/permissions-manager.php:

     'protected_roles' => ['Admin', 'SuperAdmin'],
     

   • Role Hierarchies: Extend the Role model to support hierarchical roles (e.g., Admin inherits from Editor).

3. User Assignment:

   • Livewire Integration: Use the UserPermissionsTable component to manage user-role assignments:

     use ACTTraining\PermissionsManager\Livewire\UserPermissionsTable;
     
     <livewire:user-permissions-table :users="$users" />
     

   • Gate Integration: Sync permissions with Laravel’s gates:

     Gate::define('edit-post', function ($user) {
         return $user->hasPermissionTo('edit_posts');
     });
     

4. Customization:

   • Views: Override default views in resources/views/vendor/permissions-manager/.
   • Models: Extend Permission, Role, or User models in app/Models/ to add custom logic.
   • Categories: Dynamically fetch categories from a database table or hardcode them:

     PermissionsManager::setCategories([
         'content' => ['color' => 'blue', 'label' => 'Content Management'],
         'auth'    => ['color' => 'green', 'label' => 'Authentication'],
     ]);
     

5. API Integration:

   • Expose endpoints for headless use:

     Route::get('/api/permissions', [PermissionsManager::class, 'getPermissions']);
     Route::post('/api/roles/{role}/permissions', [PermissionsManager::class, 'assignPermissionsToRole']);
     

Gotchas and Tips

Pitfalls

1. UUID Conflicts:

   • The package uses UUIDs for permissions, roles, and users. Ensure your existing Spatie models are compatible or reset the database if migrating from integer IDs.
   • Fix: Run php artisan permissions:reset-uuids (if provided) or manually update foreign keys.

2. FluxUI Pro Dependency:

   • The package requires FluxUI Pro (not the free version). Ensure your license is active or use the free components by overriding views.
   • Tip: Check resources/views/vendor/flux for customizations.

3. Livewire Caching:

   • Livewire components may cache data aggressively. Clear the cache after bulk operations:

     php artisan view:clear
     php artisan cache:clear
     

4. Protected Role Bypass:

   • Protected roles cannot be deleted via the UI. To force-delete, use the facade:

     PermissionsManager::forceDeleteRole($roleId);
     

   • Warning: This bypasses user assignment checks.

5. Permission Caching:

   • Spatie’s permission cache (spatie/laravel-permission) may cause stale data. Clear it after changes:

     php artisan permission:cache-reset
     

Debugging Tips

1. Log Permissions:

   • Enable debug mode in config/permissions-manager.php:

     'debug' => env('PERMISSIONS_DEBUG', false),
     

   • Check logs for SQL queries or permission checks.

2. TableBuilder Issues:

   • If tables render incorrectly, verify act-training/query-builder is installed and configured:

     composer require act-training/query-builder
     

3. Livewire Errors:

   • Use php artisan livewire:discover to regenerate Livewire components if you encounter class not found errors.

Extension Points

1. Custom Permission Logic:

   • Extend the Permission model to add soft deletes or custom validation:

     use ACTTraining\PermissionsManager\Models\Permission as BasePermission;
     
     class Permission extends BasePermission {
         protected $guarded = [];
         public function validateForCreation(array $data) {
             // Custom logic
         }
     }
     

2. Event Listeners:

   • Listen for permission/role events to trigger actions (e.g., notifications):

     use ACTTraining\PermissionsManager\Events\PermissionCreated;
     
     PermissionCreated::listen(function ($permission) {
         Log::info("New permission created: {$permission->name}");
     });
     

3. API Resources:

   • Transform permissions/roles for APIs using Laravel’s JsonResource:

     namespace App\Http\Resources;
     
     use ACTTraining\PermissionsManager\Models\Permission;
     
     class PermissionResource extends JsonResource {
         public function toArray($request) {
             return [
                 'id' => $this->id,
                 'name' => $this->name,
                 'category' => $this->category,
                 'description' => $this->description,
             ];
         }
     }
     

4. Testing:

   • Use the included test suite as a reference for writing tests:

     use ACTTraining\PermissionsManager\Tests\TestCase;
     
     public function testPermissionCreation() {
         $permission = PermissionsManager::createPermission('test_perm', 'test', 'Test desc');
         $this->assertDatabaseHas('permissions', ['name' => 'test_perm']);
     }