Role Manager Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require mamikon/role-manager
   

   Add to config/app.php:

   'providers' => [
       Mamikon\RoleManager\RoleManagerProvider::class,
   ],
   'aliases' => [
       'RoleManager' => Mamikon\RoleManager\RoleManagerFacade::class,
   ],
   

2. Publish Config & Views

   php artisan vendor:publish --provider="Mamikon\RoleManager\RoleManagerProvider"
   

   • Config: config/roleManager.php (default roles/permissions)
   • Views: resources/views/vendor/role-manager/ (admin panel templates)

3. Run Migrations

   php artisan migrate
   

   • Creates roles, permissions, and role_permission tables.

4. First Use Case Assign a role to a user in a controller:

   use RoleManager\Facades\RoleManager;
   
   $user = User::find(1);
   $role = RoleManager::role()->where('name', 'admin')->first();
   $user->roles()->attach($role);
   

Implementation Patterns

Core Workflows

1. Role & Permission Management

• Create Roles/Programmatically

  RoleManager::role()->create(['name' => 'editor']);
  

• Assign Permissions to Roles

  $role = RoleManager::role()->where('name', 'admin')->first();
  $role->permissions()->attach(Permission::where('name', 'edit-post')->first());
  

• Check User Permissions

  if (auth()->user()->hasPermission('edit-post')) {
      // Grant access
  }
  

2. Middleware Integration

Create a middleware to gate routes:

// app/Http/Middleware/CheckPermission.php
public function handle($request, Closure $next)
{
    if (!auth()->user()->hasPermission('edit-post')) {
        abort(403);
    }
    return $next($request);
}

Register in app/Http/Kernel.php:

protected $routeMiddleware = [
    'permission' => \App\Http\Middleware\CheckPermission::class,
];

Use in routes:

Route::get('/admin/posts', function () {
    // ...
})->middleware('permission:edit-post');

3. Admin Panel Usage

• Default Views: Published views (resources/views/vendor/role-manager/) provide CRUD interfaces for roles/permissions.
• Customize Views: Override published views in your project’s resources/views/vendor/role-manager/.
• Extend Functionality: Hook into RoleManager events (e.g., role.created) in EventServiceProvider.

4. Seeding Default Roles/Permissions

Add to DatabaseSeeder.php:

$roles = [
    ['name' => 'admin', 'description' => 'Full access'],
    ['name' => 'editor', 'description' => 'Edit content'],
];
foreach ($roles as $role) {
    RoleManager::role()->create($role);
}

$permissions = [
    ['name' => 'edit-post', 'description' => 'Edit blog posts'],
];
foreach ($permissions as $permission) {
    RoleManager::permission()->create($permission);
}

Integration Tips

• Laravel Policies: Combine with policies for granular control:

  public function update(Post $post)
  {
      $this->authorize('update-post', $post);
      // ...
  }
  

• API Gatekeeper: Use in API controllers:

  if (!auth()->user()->hasPermission('api-access')) {
      return response()->json(['error' => 'Unauthorized'], 403);
  }
  

• Blade Directives: Create a @can directive:

  Blade::if('can', function ($permission, $user = null) {
      $user = $user ?: auth()->user();
      return $user ? $user->hasPermission($permission) : false;
  });
  

  Usage:

  @can('edit-post')
      <button>Edit</button>
  @endcan
  

Gotchas and Tips

Pitfalls

1. Outdated Package:

   • Last release in 2017; test thoroughly in your Laravel version (may need compatibility tweaks).
   • Workaround: Fork the repo and update dependencies (e.g., Laravel 5.5+ support).

2. Config Overrides:

   • Default roles/permissions in config/roleManager.php overwrite database entries on migration.
   • Fix: Remove or comment out defaults before migrating if you want a clean slate.

3. Permission Caching:

   • Permissions are not cached by default. For large apps, cache auth()->user()->permissions:

     $permissions = cache()->remember("user-{$user->id}-permissions", now()->addHours(1), function () use ($user) {
         return $user->permissions;
     });
     

4. Middleware Conflicts:

   • If using auth middleware, ensure CheckPermission runs after auth to avoid null user errors.

5. View Publishing:

   • Published views assume Bootstrap 3. Update templates if using a newer CSS framework.

Debugging Tips

1. SQL Queries: Enable Laravel debugging to inspect queries:

   DB::enableQueryLog();
   $user->permissions; // Trigger query
   dd(DB::getQueryLog());
   

2. Permission Checks: Debug permission logic:

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

3. Event Listeners: Listen for role/permission changes:

   // app/Providers/EventServiceProvider.php
   protected $listen = [
       'Mamikon\RoleManager\Events\RoleCreated' => [
           'App\Listeners\LogRoleCreation',
       ],
   ];
   

Extension Points

1. Custom Permission Models: Extend the Permission model:

   class CustomPermission extends \Mamikon\RoleManager\Models\Permission
   {
       protected $table = 'custom_permissions';
   }
   

   Bind in RoleManagerProvider:

   $this->app->bind(
       \Mamikon\RoleManager\Contracts\Permission::class,
       CustomPermission::class
   );
   

2. Dynamic Permissions: Generate permissions at runtime (e.g., for resource controllers):

   $permission = RoleManager::permission()->create([
       'name' => "update-{$model->type}",
       'description' => "Update {$model->type} #{$model->id}"
   ]);
   

3. Role Hierarchies: Implement role inheritance (e.g., admin inherits editor permissions):

   // Extend Role model
   public function parents()
   {
       return $this->belongsToMany(Role::class, 'role_parents', 'child_id', 'parent_id');
   }
   

   Add a hasPermission method to check inherited permissions.

4. API Resources: Use Laravel API Resources to shape role/permission responses:

   class RoleResource extends JsonResource
   {
       public function toArray($request)
       {
           return [
               'id' => $this->id,
               'name' => $this->name,
               'permissions' => PermissionResource::collection($this->permissions),
           ];
       }
   }