Acl Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require konekt/acl
   

   Publish the migration and config:

   php artisan vendor:publish --provider="Konekt\Acl\AclServiceProvider" --tag="migrations"
   php artisan vendor:publish --provider="Konekt\Acl\AclServiceProvider" --tag="config"
   

   Run migrations:

   php artisan migrate
   

2. Model Setup: Ensure your User model uses Konekt\Acl\Concord\Models\ConcordUser as a trait:

   use Konekt\Acl\Concord\Models\ConcordUser;
   
   class User extends Authenticatable
   {
       use ConcordUser;
       // ...
   }
   

3. First Use Case: Define a role and assign permissions:

   use Konekt\Acl\Concord\Models\ConcordRole;
   
   $role = ConcordRole::create(['name' => 'admin']);
   $role->givePermissionTo('access dashboard');
   

   Assign the role to a user:

   $user->assignRole('admin');
   

   Check permissions in Blade:

   @can('access dashboard')
       <button>Go to Dashboard</button>
   @endcan
   

Implementation Patterns

Core Workflows

1. Permission Management:

   • Dynamic Permissions: Register permissions on-the-fly:

     $permission = \Konekt\Acl\Concord\Models\ConcordPermission::create(['name' => 'manage users']);
     

   • Bulk Assignment: Assign multiple permissions to a role:

     $role->givePermissionTo(['create posts', 'delete posts']);
     

2. Role Hierarchies:

   • Define hierarchical roles (e.g., admin inherits from editor):

     $adminRole = ConcordRole::create(['name' => 'admin']);
     $editorRole = ConcordRole::create(['name' => 'editor']);
     $adminRole->assignRole($editorRole); // Admin inherits editor permissions
     

3. Policy Integration:

   • Use Laravel’s policies alongside ACL:

     // app/Policies/PostPolicy.php
     public function update(User $user, Post $post)
     {
         return $user->can('edit posts');
     }
     

4. Middleware:

   • Protect routes with ACL:

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

5. Concord Compliance:

   • Leverage Concord’s module system for modular permissions:

     // In a Concord module's boot method
     $this->acl()->role('editor')->givePermissionTo('publish content');
     

Integration Tips

• Seeding Permissions: Use a seeder to initialize roles/permissions:

  public function run()
  {
      $admin = ConcordRole::create(['name' => 'admin']);
      $admin->givePermissionTo(['access dashboard', 'manage users']);
  }
  

• API Authorization: Use can in API controllers:

  public function destroy(Post $post)
  {
      $this->authorize('delete', $post); // Uses Laravel's authorize helper
      // OR
      if (!$this->user()->can('delete posts')) {
          abort(403);
      }
  }
  

• Caching: Cache role-permission mappings for performance:

  \Konekt\Acl\Concord\Facades\Acl::cacheRolesAndPermissions();
  

Gotchas and Tips

Pitfalls

1. Migration Conflicts:

   • If using Spatie’s original migrations, drop them first to avoid conflicts:

     php artisan migrate:reset
     php artisan migrate
     

2. Permission Caching:

   • Clear cached permissions after dynamic changes:

     php artisan cache:clear
     

   • Or manually:

     \Konekt\Acl\Concord\Facades\Acl::clearCachedPermissions();
     

3. Case Sensitivity:

   • Permission names are case-sensitive. Use constants or strings consistently:

     define('PERMISSION_EDIT_ARTICLES', 'edit articles');
     

4. Role Assignment:

   • Directly assigning roles to users bypasses role hierarchies. Use assignRole for hierarchical roles:

     // Correct (respects hierarchy)
     $user->assignRole('admin');
     
     // Avoid (skips hierarchy)
     $user->roles()->attach($adminRole->id);
     

5. Concord Module Isolation:

   • Permissions defined in one Concord module won’t auto-propagate to others. Explicitly share or redefine them.

Debugging

• Check Permissions: Dump a user’s permissions:

  dd($user->getAllPermissions()->pluck('name'));
  

• Gate Debugging: Enable Laravel’s gate debugging:

  Gate::inspect();
  

• Log Middleware: Add middleware to log permission checks:

  public function handle($request, Closure $next)
  {
      if ($request->user() && $request->user()->can('log permission checks')) {
          \Log::info('Permission check:', ['user' => $request->user()->id, 'permission' => $request->route()->getName()]);
      }
      return $next($request);
  }
  

Extension Points

1. Custom Permission Models: Extend ConcordPermission or ConcordRole:

   class CustomPermission extends \Konekt\Acl\Concord\Models\ConcordPermission
   {
       protected $table = 'custom_permissions';
   }
   

2. Event Listeners: Listen for permission/role events:

   // app/Providers/EventServiceProvider.php
   protected $listen = [
       \Konekt\Acl\Events\RoleCreated::class => [
           \App\Listeners\LogRoleCreation::class,
       ],
   ];
   

3. Custom Guards: Override the default guard in config/acl.php:

   'guard_name' => 'admin',
   

4. API Resources: Extend ACL models in API resources:

   public function toArray($request)
   {
       return [
           'id' => $this->id,
           'name' => $this->name,
           'permissions' => $this->permissions->pluck('name'),
       ];
   }
   

5. Testing: Use ConcordTestingTrait for tests:

   use Konekt\Acl\Concord\Testing\ConcordTestingTrait;
   
   class PermissionTest extends TestCase
   {
       use ConcordTestingTrait;
   
       public function test_user_has_permission()
       {
           $user = $this->createUserWithRole('admin');
           $this->assertTrue($user->can('access dashboard'));
       }
   }