Laravel Acl Laravel Package

Getting Started

Install via Composer:

composer require mateusjunges/laravel-acl:^4.2

Publish the package configuration and migrations:

php artisan vendor:publish --provider="MateusJunges\LaravelAcl\AclServiceProvider" --tag="config"
php artisan migrate

For Laravel 10 projects, ensure your phpunit.xml and composer.json reflect PHP 8.0+ requirements. The package now drops PHP 7.4 support.

First Use Case: Define a role and permission in a migration or seeder:

use MateusJunges\LaravelAcl\Models\Role;
use MateusJunges\LaravelAcl\Models\Permission;

// Create a role
$adminRole = Role::create(['name' => 'admin']);

// Assign permissions
$adminRole->permissions()->attach([
    Permission::where('name', 'access_dashboard')->first(),
    Permission::where('name', 'manage_users')->first(),
]);

Implementation Patterns

Role-Based Access Control (RBAC)

Leverage middleware for route protection:

Route::middleware(['role:admin'])->group(function () {
    Route::get('/admin/dashboard', [DashboardController::class, 'index']);
});

Dynamic Permission Checks

Use the can() helper or facade in controllers/views:

if (auth()->user()->can('manage_users')) {
    // Grant access
}

Policy Integration

Extend Laravel’s built-in policies with ACL:

use MateusJunges\LaravelAcl\Policies\AclPolicy;

class PostPolicy extends AclPolicy
{
    public function update(User $user, Post $post)
    {
        return $user->can('edit_posts') || $user->id === $post->user_id;
    }
}

Bulk Assignments

Attach/detach permissions in bulk:

$role->permissions()->sync([1, 2, 3]); // Attach IDs 1, 2, 3

Gotchas and Tips

Laravel 10 Compatibility

• PHP Version: Ensure your project uses PHP 8.0+ (PHP 7.4 is no longer supported).
• Testing: Update phpunit.xml to reflect PHP 8.0+ syntax (e.g., strict_types=1 in config).

Migration Quirks

• If upgrading from v4.1.x, run php artisan migrate to update the roles and permissions tables (schema changes may apply).
• Seeders should use Role::firstOrCreate() and Permission::firstOrCreate() to avoid duplicates.

Performance Tips

• Cache role-permission relationships for high-traffic apps:

  Cache::remember('user-permissions-' . auth()->id(), now()->addHours(1), function () {
      return auth()->user()->permissions()->pluck('name');
  });
  

Debugging

• Permission Denied? Verify the user’s role-permission assignments:

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

• Middleware Issues: Ensure role: middleware is registered in app/Http/Kernel.php:

  'role' => \MateusJunges\LaravelAcl\Middleware\RoleMiddleware::class,
  

Extension Points

• Custom Guards: Override the AclServiceProvider to bind custom guards:

  $this->app->bind('acl.guard', function () {
      return new CustomGuard();
  });
  

• Permission Models: Extend MateusJunges\LaravelAcl\Models\Permission to add custom fields (e.g., description).