Laravel Permission Editor Laravel Package

Getting Started

Minimal Setup

1. Prerequisite: Ensure spatie/laravel-permission is installed and configured in your Laravel project.

   composer require spatie/laravel-permission
   php artisan migrate
   

2. Install the Editor:

   composer require ihtisham467/laravel-permission-editor
   

3. Publish Assets & Config:

   php artisan vendor:publish --provider="Ihtisham467\LaravelPermissionEditor\PermissionEditorServiceProvider"
   

   • This generates:
     • config/permission-editor.php (for route/middleware customization)
     • Assets (JS/CSS) in public/vendor/laravel-permission-editor.

4. First Use Case:

   • Access /permission-editor/roles in your browser.
   • Default UI: Displays a tree-view of roles/permissions with checkboxes for assignment.
   • Default Routes:
     • /permission-editor/roles (list/edit roles)
     • /permission-editor/permissions (list/edit permissions)
     • /permission-editor/role-permissions (assign permissions to roles).

Implementation Patterns

Core Workflows

1. Role Management:

   • Create/Edit: Click the "+" button to add a role. Edit via the pencil icon.
   • Bulk Actions: Select multiple roles (checkboxes) to delete or assign permissions.
   • Search/Filter: Use the search bar to find roles by name.

2. Permission Assignment:

   • Tree View: Permissions are grouped hierarchically (e.g., posts.create, posts.edit under posts).
   • Drag-and-Drop: Reorder permissions/roles by dragging items (if enabled in config).
   • Bulk Assignment: Check/uncheck parent nodes to assign permissions recursively.

3. Integration with Spatie:

   • The editor mirrors Spatie’s data model (e.g., Role::findOrCreate(), Permission::create()).
   • No direct DB queries: All CRUD operations delegate to Spatie’s underlying methods.
   • Example:

     // Manually sync permissions (if needed outside the UI):
     $role = Role::find(1);
     $role->givePermissionTo('edit_posts'); // Uses Spatie's logic
     

4. Middleware & Security:

   • Default Routes: Unprotected by default. Secure them in config/permission-editor.php:

     'middleware' => ['auth', 'verified'], // Add your middleware
     

   • Gate Integration: Use Laravel’s gates to restrict access:

     Gate::define('manage-permissions', function ($user) {
         return $user->hasRole('admin');
     });
     

5. Customization:

   • Override Views: Publish views with --tag=views and modify:

     php artisan vendor:publish --tag=views --provider="Ihtisham467\LaravelPermissionEditor\PermissionEditorServiceProvider"
     

     • Edit files in resources/views/vendor/laravel-permission-editor/.
   • Extend Permissions: Add custom permissions via Spatie’s facade:

     Permission::create('custom.namespace.action');
     

Gotchas and Tips

Pitfalls

1. Route Conflicts:

   • The package registers routes under /permission-editor/. If you have a route like /admin/permissions, add a prefix in the config:

     'prefix' => 'admin',
     

   • Fix: Use Route::namespace() or adjust middleware in routes/web.php.

2. Permission Hierarchy Issues:

   • The UI assumes permissions are dot-notation (e.g., posts.create). If you use custom formats, the tree view may break.
   • Workaround: Extend the blade template to handle custom formats.

3. Caching:

   • The UI caches role/permission data. Clear it after manual Spatie operations:

     php artisan cache:clear
     

   • Tip: Disable caching in config/permission-editor.php for development:

     'cache_enabled' => env('APP_DEBUG') ? false : true,
     

4. Asset Loading:

   • If assets fail to load, check:
     • The public/vendor/laravel-permission-editor directory exists.
     • No custom mix manifest conflicts (e.g., Vite/Laravel Mix).
   • Fix: Manually link assets in your layout:

     <link href="{{ asset('vendor/laravel-permission-editor/css/editor.css') }}" rel="stylesheet">
     

5. Permission Sync Delays:

   • Changes in the UI may not reflect immediately in your app if:
     • You’re using Permission::cacheResolved().
     • Middleware caches roles (e.g., Role::resolveGate()).
   • Debug: Temporarily disable caching:

     Permission::cacheResolved(false);
     

Debugging Tips

1. Log Operations:

   • Enable Spatie’s debug mode to log permission changes:

     config(['permission.debug' => true]);
     

   • Check Laravel logs for errors during UI interactions.

2. Check Published Config:

   • Verify config/permission-editor.php for:
     • Correct middleware.
     • Disabled features (e.g., drag_and_drop_enabled).

3. Database Consistency:

   • If roles/permissions appear missing:
     • Run Spatie’s migrations again.
     • Check for soft-deleted records:

       php artisan db:seed --class=PermissionTableSeeder
       

Extension Points

1. Custom UI Components:

   • Override the tree view by extending the PermissionTree Vue component (published in resources/js/components).
   • Example: Add a custom permission type:

     // resources/js/components/PermissionTree.vue
     methods: {
         renderPermission(permission) {
             if (permission.namespace === 'custom') {
                 return h('span', { class: 'custom-permission' }, permission.name);
             }
             return h('span', permission.name);
         }
     }
     

2. API Endpoints:

   • The package uses Laravel’s controller. Extend it to add custom logic:

     // app/Http/Controllers/PermissionEditorController.php
     public function customAction() {
         // Add logic here
     }
     

   • Update routes in routes/web.php to include your endpoint.

3. Localization:

   • Translate UI labels by publishing language files:

     php artisan vendor:publish --tag=lang --provider="Ihtisham467\LaravelPermissionEditor\PermissionEditorServiceProvider"
     

   • Edit resources/lang/en/permission-editor.php.

4. Testing:

   • Mock the editor in tests by overriding its dependencies:

     $this->partialMock(Ihtisham467\LaravelPermissionEditor\Http\Controllers\PermissionEditorController::class, 'methodName');
     

   • Test routes with:

     $response = $this->actingAs($user)->get('/permission-editor/roles');
     $response->assertStatus(200);