Entrust Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require zizaco/entrust:^5.2
   

   Add to config/app.php:

   'providers' => [
       Zizaco\Entrust\EntrustServiceProvider::class,
   ],
   'aliases' => [
       'Entrust' => Zizaco\Entrust\Facades\Entrust::class,
   ]
   

2. Publish Config & Migrations:

   php artisan vendor:publish --provider="Zizaco\Entrust\EntrustServiceProvider" --tag="migrations"
   php artisan vendor:publish --provider="Zizaco\Entrust\EntrustServiceProvider" --tag="config"
   php artisan migrate
   

3. First Use Case:

   // Create a role
   $adminRole = \App\Models\Role::create(['name' => 'admin']);
   
   // Create a permission
   $editPermission = \App\Models\Permission::create(['name' => 'edit-articles']);
   
   // Assign permission to role
   $adminRole->attachPermission($editPermission);
   
   // Assign role to user
   $user->attachRole($adminRole);
   
   // Check if user can perform action
   if ($user->can('edit-articles')) {
       // Grant access
   }
   

Key Files to Review First

• config/entrust.php (customize role-permission relationships)
• app/Models/Role.php, app/Models/Permission.php, app/Models/User.php (extend base models)
• app/Providers/EntrustServiceProvider.php (customize service binding)

Implementation Patterns

Core Workflows

1. Role-Permission Assignment:

   // Bulk assign permissions to role
   $role->attachPermissions([$perm1, $perm2]);
   
   // Bulk assign roles to user
   $user->attachRoles([$role1, $role2]);
   

2. Permission Checks:

   // Direct permission check
   if (Entrust::can('edit-articles')) {
       // ...
   }
   
   // Check via user model
   if ($user->hasRole('admin')) {
       // ...
   }
   
   // Check for any role in collection
   if ($user->hasAnyRole(['admin', 'editor'])) {
       // ...
   }
   

3. Middleware Integration:

   // In routes/web.php
   Route::get('/admin', function () {
       // ...
   })->middleware('role:admin');
   
   // Or for permissions
   Route::get('/edit', function () {
       // ...
   })->middleware('permission:edit-articles');
   

4. Blade Directives:

   @can('edit-articles')
       <button>Edit</button>
   @endcan
   
   @role('admin')
       <div>Admin Panel</div>
   @endrole
   

Advanced Patterns

1. Dynamic Permission Generation:

   // Generate permissions from a model's methods
   $article = new \App\Models\Article();
   $permissions = collect($article->getFillable())
       ->map(fn($field) => "edit-article-{$field}")
       ->toArray();
   

2. Policy Integration:

   use Zizaco\Entrust\Entrust;
   
   class ArticlePolicy {
       public function update(User $user, Article $article) {
           return $user->can("edit-article-{$article->id}");
       }
   }
   

3. API Gate Integration:

   use Laravel\Sanctum\PersonalAccessToken;
   use Zizaco\Entrust\Entrust;
   
   PersonalAccessToken::creating(function ($token) {
       $token->abilities = Entrust::abilities();
   });
   

4. Seeding Roles/Permissions:

   // database/seeders/EntrustSeeder.php
   public function run() {
       $adminRole = Role::create(['name' => 'admin']);
       $permissions = Permission::create([
           ['name' => 'manage-users'],
           ['name' => 'manage-content']
       ]);
       $adminRole->attachPermissions($permissions);
   }
   

Gotchas and Tips

Common Pitfalls

1. Model Relationships:

   • Ensure your User model has roles() and permissions() relationships defined:

     public function roles() {
         return $this->belongsToMany(Role::class);
     }
     public function permissions() {
         return $this->belongsToMany(Permission::class);
     }
     

2. Caching Issues:

   • Clear cached permissions when roles/permissions change:

     Entrust::clearResolvedCache();
     

3. Middleware Conflicts:

   • Order matters! Place role/permission middleware after auth middleware in $routeMiddleware.

4. Soft Deletes:

   • If using soft deletes, ensure your models extend Zizaco\Entrust\Traits\SoftDeletingTrait:

     use Zizaco\Entrust\Traits\SoftDeletingTrait;
     
     class Role extends Model {
         use SoftDeletingTrait;
     }
     

Debugging Tips

1. Check Resolved Abilities:

   dd(Entrust::abilities()); // Debug current user's permissions
   

2. Log Permission Checks:

   if (Entrust::can('edit-articles', true)) {
       // Returns boolean and logs the check
   }
   

3. Verify Database:

   php artisan tinker
   >> \App\Models\Role::with('permissions')->get();
   >> \App\Models\User::with('roles', 'permissions')->find(1);
   

Extension Points

1. Custom Permission Resolver:

   // In EntrustServiceProvider
   $this->app->bind('entrust.permission.resolver', function() {
       return new CustomPermissionResolver();
   });
   

2. Override Default Models:

   // In config/entrust.php
   'models' => [
       'role' => \App\Models\CustomRole::class,
       'permission' => \App\Models\CustomPermission::class,
   ],
   

3. Custom Permission Namespaces:

   // Generate namespaced permissions
   $permission = \App\Models\Permission::create([
       'name' => 'content.articles.edit',
       'display_name' => 'Edit Articles'
   ]);
   

4. Event Listeners:

   // Listen for role assignment
   Event::listen('entrust.role-assigned', function ($user, $role) {
       // Log or notify
   });
   

Performance Tips

1. Eager Load Relationships:

   $user = User::with(['roles', 'permissions'])->find(1);
   

2. Cache Permission Checks:

   // In config/entrust.php
   'cache' => true,
   

3. Batch Operations:

   // Use detach() for bulk removal
   $user->detachRoles([$role1, $role2]);