Laravel Acl Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require mateusjunges/laravel-acl
   

   Publish the migration and config:

   php artisan vendor:publish --provider="MateusJunges\LaravelAcl\LaravelAclServiceProvider"
   php artisan migrate
   

2. Define Roles/Groups: Use the Role and Group models to create roles/groups via Tinker or migrations:

   use MateusJunges\LaravelAcl\Models\Role;
   use MateusJunges\LaravelAcl\Models\Group;
   
   Role::create(['name' => 'Admin']);
   Group::create(['name' => 'Editors']);
   

3. Assign Permissions: Attach permissions to roles/groups:

   $role = Role::find(1);
   $role->attachPermission('create-post'); // Define 'create-post' in config/acl.php
   

4. First Use Case: Check if a user (or model) has permission:

   if (auth()->user()->can('create-post')) {
       // Allow action
   }
   

Implementation Patterns

Core Workflows

1. Role-Based Access Control (RBAC):

   • Assign roles to users/models:

     $user->attachRole($role);
     

   • Check permissions via middleware or directly:

     if ($user->can('edit-post')) { ... }
     

2. Group-Based Permissions:

   • Assign groups to users/models:

     $user->attachGroup($group);
     

   • Groups inherit permissions from attached roles.

3. Dynamic Permission Checks:

   • Use can() with optional subject (e.g., model):

     $post->author->can('delete', $post); // Custom logic via `can()` method
     

4. Middleware Integration:

   • Protect routes with:

     Route::get('/admin', function () {
         // ...
     })->middleware('can:manage-admin');
     

5. Policy Integration:

   • Extend Laravel’s policies:

     use MateusJunges\LaravelAcl\Traits\HasPermissions;
     
     class PostPolicy extends Policy {
         use HasPermissions;
         // Custom logic
     }
     

Integration Tips

• Seeding Permissions: Use database seeds to predefine roles/groups/permissions:

  public function run()
  {
      $adminRole = Role::create(['name' => 'Admin']);
      $adminRole->attachPermissions(['create-post', 'delete-post']);
  }
  

• API Gate Integration: Leverage Laravel’s Gate for fine-grained control:

  Gate::define('edit-post', function ($user, $post) {
      return $user->can('edit-post') && $post->user_id === $user->id;
  });
  

• Caching: Enable caching in config/acl.php for performance:

  'cache' => [
      'enabled' => true,
      'driver' => 'file',
  ],
  

Gotchas and Tips

Pitfalls

1. Permission Caching:

   • Clear cache after permission changes:

     php artisan cache:clear
     

   • Or manually:

     \MateusJunges\LaravelAcl\Cache::clear();
     

2. Model Binding:

   • Ensure models use HasPermissions trait:

     use MateusJunges\LaravelAcl\Traits\HasPermissions;
     
     class User extends Authenticatable {
         use HasPermissions;
     }
     

3. Permission Names:

   • Define permissions in config/acl.php under permissions:

     'permissions' => [
         'create-post' => 'Create Post',
         'delete-post' => 'Delete Post',
     ],
     

   • Use kebab-case for consistency.

4. Middleware Conflicts:

   • If using can middleware, ensure the permission key matches exactly (e.g., can:create-post).

5. Mass Assignment:

   • Avoid mass-assigning permissions/roles directly; use the provided methods (attachRole, attachPermission).

Debugging

• Check Permissions: Log permissions for debugging:

  dd(auth()->user()->permissions->pluck('name'));
  

• SQL Queries: Enable Laravel’s query logging:

  \DB::enableQueryLog();
  auth()->user()->can('create-post'); // Check last query
  dd(\DB::getQueryLog());
  

• Cache Issues: Verify cache driver in config/acl.php and clear it if permissions aren’t updating.

Extension Points

1. Custom Permission Logic: Override the can() method in your model:

   public function can($permission, $subject = null)
   {
       if ($permission === 'custom-permission') {
           return $this->isAdmin();
       }
       return parent::can($permission, $subject);
   }
   

2. Event Listeners: Listen for permission changes:

   \MateusJunges\LaravelAcl\Events\PermissionAttached::class => [
       \App\Listeners\LogPermissionChange::class,
   ],
   

3. Custom Storage: Extend the Permission model to use a custom storage backend (e.g., Redis).

4. Localization: Localize permission names by overriding the getDisplayName() method in the Permission model.

5. Testing: Use actingAs() with permissions in tests:

   $user = User::factory()->create();
   $user->attachRole($adminRole);
   $this->actingAs($user)->get('/admin')->assertOk();