Permission Manager Laravel Package

Getting Started

Minimal Steps to First Use

1. Installation Run composer require codeflextech/permission-manager and publish the config (php artisan vendor:publish --tag=permission-manager-config) and CSS (php artisan vendor:publish --provider="CodeFlexTech\PermissionManager\PermissionManagerServiceProvider" --tag=permission-manager-assets).

2. Run Migrations Execute php artisan migrate to set up the required tables (permissions, roles, model_has_permissions, model_has_roles).

3. Configure Middleware Add the permission-manager middleware to your routes (e.g., Route::middleware(['auth', 'permission-manager'])->group(...)) or use the default guard in the config.

4. First Access Visit /permission-manager (or your configured route prefix) to access the dashboard. The UI will auto-detect permission groups from your existing spatie/laravel-permission setup.

5. Quick Action Create a new role (e.g., "Editor") and assign permissions like posts.create or users.edit via the visual checkbox matrix.

Where to Look First

• Dashboard: /permission-manager – Overview of roles, permissions, and user counts.
• Permissions CRUD: /permission-manager/permissions – Manage individual permissions with dot-notation grouping.
• Roles CRUD: /permission-manager/roles – Create/edit roles with bulk permission assignment.
• Config File: config/permission-manager.php – Adjust middleware, guards, or route prefixes.

First Use Case: Assigning Permissions to a Role

1. Navigate to Roles → Create Role (e.g., "Content Manager").
2. Use the Permission Groups panel to select/deselect all permissions in a group (e.g., posts.*).
3. Save the role and assign it to users via the User → Roles tab in the Laravel Nova/Forge UI or custom admin panel.

Implementation Patterns

Core Workflows

1. Permission Management

• Bulk Editing: Use the "Select All" checkboxes in the permission matrix to assign/deselect groups (e.g., posts.*).
• Dot-Notation Grouping: Permissions like posts.create auto-group under "posts" in the UI.
• Search Filtering: Livewire-powered search filters permissions/roles in real-time (no page reload).

2. Role Assignment

• User → Roles: Assign multiple roles to a user via the /permission-manager/users/{id}/roles endpoint (if integrated with Laravel’s user model).
• Role → Users: View a count of users assigned to a role directly in the Roles table.

3. Integration with Existing Auth

• Middleware: Protect routes with @can('permission-manager.access') or via middleware:

  Route::middleware(['auth', 'permission-manager'])->group(function () {
      // Admin-only routes
  });
  

• Guard Configuration: Override the default guard in config/permission-manager.php:

  'guard' => 'admin', // Use a custom guard (e.g., Sanctum, Passport)
  

4. Customizing the UI

• Layout Overrides: Publish and modify the Blade views:

  php artisan vendor:publish --tag=permission-manager-views
  

  Key files: resources/views/vendor/permission-manager/layouts/app.blade.php.
• CSS Overrides: Extend the standalone CSS by publishing assets and adding custom styles to public/css/permission-manager.css.

5. Extending Functionality

• Custom Permission Groups: Override the auto-grouping logic by extending the PermissionGroup class or hooking into the grouping event.
• API Endpoints: Use the underlying spatie/laravel-permission methods in your controllers:

  use Spatie\Permission\Models\Permission;
  use Spatie\Permission\Models\Role;
  
  // Example: Create a permission programmatically
  Permission::create(['name' => 'reports.export']);
  
  // Assign a role to a user
  $user->assignRole('Content Manager');
  

Integration Tips

Laravel Nova/Forge

• Nova Tool: Integrate the package’s routes into Nova by adding a custom tool or linking to /permission-manager in the Nova menu.
• Forge: Use the package’s middleware to restrict access to Forge environments.

Livewire Components

• Reuse Components: Extract the permission matrix or role assignment components for use in other Livewire apps:

  use CodeFlexTech\PermissionManager\Livewire\PermissionMatrix;
  
  // In your Livewire component
  public PermissionMatrix;
  

Testing

• Unit Tests: Test permission assignments with spatie/laravel-permission helpers:

  $user->givePermissionTo('posts.create');
  $this->assertTrue($user->hasPermissionTo('posts.create'));
  

• Feature Tests: Test UI interactions with Livewire’s testing tools:

  $this->livewire(PermissionMatrix::class)
       ->set('selectedPermissions', ['posts.create'])
       ->assertSee('posts.create');
  

Gotchas and Tips

Pitfalls

1. CSS Conflicts

   • The package ships with standalone CSS, but if you customize it, ensure your overrides target the correct classes (e.g., .permission-group, .role-card).
   • Fix: Use browser dev tools to inspect elements and adjust specificity.

2. Super Admin Lock

   • The package prevents deletion of the default "Super Admin" role. If you need to customize this, override the canDeleteRole method in the Role model or publish the views and modify the delete button logic.

3. Permission Grouping Logic

   • The auto-grouping splits dot-notation permissions at the first dot (e.g., posts.create → group "posts"). If your permissions use a different delimiter (e.g., posts:create), you’ll need to extend the PermissionGroup class or override the grouping logic in the config:

     'permission_group_delimiter' => ':', // Custom delimiter
     

4. Livewire Caching

   • Livewire components may cache data aggressively. Clear the cache if changes to permissions/roles aren’t reflecting:

     php artisan view:clear
     php artisan cache:clear
     

5. Middleware Timing

   • Ensure the permission-manager middleware is registered after the auth middleware in your HandleIncomingRequests middleware group. Misordering can cause infinite redirects.

6. User Model Assumptions

   • The package assumes your user model uses Spatie\Permission\Traits\HasRoles and HasPermissions. If you’re using a custom trait, update the config:

     'user_model' => App\Models\CustomUser::class,
     

Debugging Tips

1. Log Permission Groups Add this to your AppServiceProvider to debug grouping:

   use CodeFlexTech\PermissionManager\Services\PermissionGroup;
   
   public function boot()
   {
       PermissionGroup::macro('logGroups', function () {
           \Log::info('Permission Groups:', [
               'groups' => PermissionGroup::getGroups()
           ]);
       });
   }
   

2. Check Livewire Events Enable Livewire logging to debug component interactions:

   LIVEWIRE_LOG=1 php artisan serve
   

3. Verify Middleware Test middleware isolation by temporarily removing it and checking if routes are accessible:

   // Temporarily disable in routes.php
   Route::middleware(['auth'])->group(...); // Remove 'permission-manager'
   

Extension Points

1. Custom Permission Groups Extend the PermissionGroup class to support custom grouping logic:

   namespace App\Services;
   
   use CodeFlexTech\PermissionManager\Services\PermissionGroup as BasePermissionGroup;
   
   class CustomPermissionGroup extends BasePermissionGroup
   {
       public function getGroupForPermission(string $permission): string
       {
           // Custom logic (e.g., split by '::' instead of '.')
           return explode('::', $permission)[0];
       }
   }
   

   Then bind it in AppServiceProvider:

   $this->app->bind(
       \CodeFlexTech\PermissionManager\Contracts\PermissionGroup::class,
       App\Services\CustomPermissionGroup::class
   );
   

2. Add Custom Fields to Roles Extend the Role model and update the Livewire components:

   // app/Models/Role.php
   use Illuminate\Database\Eloquent\Relations\HasMany;
   
   public function customFields(): HasMany
   {
       return $this->hasMany(RoleCustomField::class);
   }
   

   Publish the views and add the fields to the RoleCreateEdit Livewire component.

3. API-Only Usage Disable the UI and use the underlying spatie/laravel-permission methods directly. Set this in config:

   'enable_ui' => false,
   

4. Multi-Guard Support Extend the package to support multiple guards (e.g., web + api) by overriding