Laravel Permission Generator Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require saeidsharafi/laravel-permission-generator
   php artisan vendor:publish --provider="SaeidSharafi\PermissionGenerator\PermissionGeneratorServiceProvider" --tag="config"
   

2. Configure Permissions Edit config/permission-generator.php to define your permission structure:

   'permissions' => [
       'posts' => [
           'actions' => ['create', 'read', 'update', 'delete'],
           'scoped' => ['view_any', 'manage_any'],
       ],
       'comments' => [
           'actions' => ['create', 'read', 'update', 'delete', 'approve'],
       ],
       'custom' => [
           'moderate_content',
           'manage_users',
       ],
   ],
   

3. Generate Permissions

   php artisan permission:generate
   

   This creates app/Enums/Permission.php with type-safe permission constants.

4. First Use Case Replace hardcoded strings with the generated enum:

   use App\Enums\Permission;
   
   // Before
   $user->givePermissionTo('posts.read');
   
   // After
   $user->givePermissionTo(Permission::POSTS_READ);
   

Implementation Patterns

Workflow Integration

1. Permission Definition

   • Use the config file to define all permissions in one place.
   • Group permissions by resource (e.g., posts, comments) with standard CRUD actions.
   • Add custom permissions under the custom key or as standalone entries.

2. Generating and Syncing

   • Run php artisan permission:generate to update the Permission enum.
   • Sync with Spatie’s database tables using:

     php artisan permission:sync --super-admin=admin
     

     (Assigns all permissions to a "Super Admin" role.)

3. Usage in Code

   • Type Safety: Use autocompletion in IDEs (e.g., Permission:: + Ctrl+Space).
   • Middleware:

     use App\Enums\Permission;
     
     public function handle($request, Closure $next) {
         if ($request->user()->hasPermissionTo(Permission::POSTS_UPDATE)) {
             return $next($request);
         }
         abort(403);
     }
     

   • Policy Methods:

     public function update(User $user, Post $post) {
         return $user->hasPermissionTo(Permission::POSTS_UPDATE);
     }
     

4. Scoped Permissions

   • Define scoped actions in config (e.g., view_any) to generate both:
     • posts.view_any (scoped permission)
     • posts.view (standard permission).
   • Use in code:

     $user->hasPermissionTo(Permission::POSTS_VIEW_ANY);
     

5. Custom Permissions

   • Define custom permissions as strings or enums:

     'custom' => [
         'moderate_content',
         'CustomEnum::VALUE', // Supports custom enums
     ],
     

   • Reference in code:

     Permission::MODERATE_CONTENT;
     // or
     Permission::CUSTOM_ENUM_VALUE;
     

6. Role Assignment

   • Assign permissions to roles via Spatie’s Role model:

     $role->givePermissionTo([
         Permission::POSTS_CREATE,
         Permission::COMMENTS_APPROVE,
     ]);
     

7. Gate/Policy Integration

   • Replace string-based gates with enum constants:

     Gate::define('delete-post', function (User $user, Post $post) {
         return $user->hasPermissionTo(Permission::POSTS_DELETE);
     });
     

Gotchas and Tips

Pitfalls

1. Enum Regeneration

   • Regenerating the enum overwrites the file. Backup or use version control for app/Enums/Permission.php.
   • Tip: Commit the generated file to track changes or use a template file.

2. Spatie Permission Dependency

   • The package requires spatie/laravel-permission. Install it first:

     composer require spatie/laravel-permission
     php artisan vendor:publish --provider="Spatie\Permission\PermissionServiceProvider"
     

   • Gotcha: If you skip this, the permission:sync command will fail.

3. Permission Naming Conflicts

   • Avoid duplicate permission names (e.g., posts.create vs. create_post).
   • Tip: Use a consistent naming convention (e.g., resource.action).

4. Scoped Permissions Quirk

   • Scoped permissions (e.g., view_any) generate two entries in the enum:
     • POSTS_VIEW_ANY
     • POSTS_VIEW
   • Gotcha: Ensure your config explicitly lists both if needed.

5. Custom Enum Support

   • Custom enums (e.g., CustomEnum::VALUE) must be autoloaded and available at runtime.
   • Tip: Place custom enums in app/Enums/ and ensure they’re imported in composer.json:

     "autoload": {
         "psr-4": {
             "App\\Enums\\": "app/Enums/"
         }
     }
     

6. Database Sync Issues

   • Running permission:sync replaces existing permissions. Test in a staging environment first.
   • Tip: Use --dry-run flag (if available) to preview changes:

     php artisan permission:sync --dry-run
     

7. IDE Autocompletion

   • Some IDEs (e.g., PHPStorm) may not auto-detect the generated enum. Fix:
     • Mark the app/Enums/ directory as a "Sources Root" in IDE settings.
     • Add this to composer.json:

       "extra": {
           "laravel": {
               "enum-directories": ["app/Enums"]
           }
       }
       

Debugging Tips

1. Check Generated Enum

   • After running permission:generate, inspect app/Enums/Permission.php for errors.
   • Tip: Use php artisan permission:generate --verbose for debug output.

2. Verify Database Sync

   • After syncing, verify permissions in the permissions table:

     SELECT * FROM permissions;
     

   • Check role-permission assignments:

     SELECT * FROM model_has_permissions;
     

3. Handle Missing Permissions

   • If a permission is missing after sync, regenerate the enum and resync:

     php artisan permission:generate
     php artisan permission:sync
     

4. Permission Caching

   • Spatie’s permission system caches roles/permissions. Clear cache if changes aren’t reflected:

     php artisan cache:clear
     php artisan config:clear
     

Extension Points

1. Custom Permission Logic

   • Extend the generator by publishing and modifying the template:

     php artisan vendor:publish --provider="SaeidSharafi\PermissionGenerator\PermissionGeneratorServiceProvider" --tag="templates"
     

   • Edit resources/views/vendor/permission-generator/permission.php to customize the enum structure.

2. Dynamic Permission Generation

   • For dynamic permissions (e.g., per-tenant), override the PermissionGenerator class:

     namespace App\Services;
     
     use SaeidSharafi\PermissionGenerator\PermissionGenerator as BaseGenerator;
     
     class PermissionGenerator extends BaseGenerator {
         public function generate(): string {
             // Add dynamic logic here
             return parent::generate();
         }
     }
     

   • Bind it in AppServiceProvider:

     $this->app->bind(
         SaeidSharafi\PermissionGenerator\PermissionGenerator::class,
         App\Services\PermissionGenerator::class
     );
     

3. Custom Artisan Commands

   • Extend the existing commands by creating a new command that uses the generator:

     use SaeidSharafi\PermissionGenerator\PermissionGenerator;
     
     class CustomPermissionCommand extends Command {
         protected $generator;
     
         public function __construct(PermissionGenerator $generator) {
             parent::__construct();
             $this->generator = $generator;
         }
     
         public function handle() {
             $this->generator->setCustomOption(true);
             $this->generator->generate();
         }
     }