Permissionmanager Laravel Package

Getting Started

Backpack PermissionManager is an admin UI for users, roles, and permissions built on Backpack CRUD and spatie/laravel-permission. Treat it as a management layer, not an authorization layer—enforcement still happens through Spatie middleware, Gates, and policies.

Minimal setup:

1. Install Backpack CRUD and authentication first, then:

   composer require backpack/permissionmanager
   

2. Publish and run Spatie’s migrations if you do not already have them:

   php artisan vendor:publish --provider="Spatie\Permission\PermissionServiceProvider"
   php artisan migrate
   

3. Publish the package config and inspect it:

   php artisan vendor:publish --provider="Backpack\PermissionManager\PermissionManagerServiceProvider" --tag=config
   

   Look at config/backpack/permissionmanager.php for model mappings, route prefix, and middleware. Also look at Spatie’s config/permission.php for guards and cache settings.
4. Ensure your User model uses Spatie\Permission\Traits\HasRoles.
5. Log in to /admin/user (or your configured prefix), create a role such as admin, assign permissions, and attach the role to your user.

First use case: create an admin role, give it broad permissions, assign it to yourself, then protect one Backpack CRUD route with permission:access admin and verify that a non-admin user is blocked.

Where to look first:

• config/backpack/permissionmanager.php — models, routes, UI behavior.
• Package CRUD controllers — UserCrudController, RoleCrudController, PermissionCrudController.
• config/permission.php — guards, cache, table names.
• Spatie’s HasRoles trait — the actual API you will use in application code.

Implementation Patterns

Use the UI for assignment, seeders for definitions. Day-to-day, admins assign roles and permissions through the UI. Developers should define canonical permissions in seeders so environments do not drift:

use Spatie\Permission\Models\Permission;
use Spatie\Permission\Models\Role;

foreach (['access admin', 'edit articles', 'delete articles'] as $name) {
    Permission::firstOrCreate(['name' => $name, 'guard_name' => 'web']);
}

$admin = Role::firstOrCreate(['name' => 'admin', 'guard_name' => 'web']);
$admin->syncPermissions(Permission::all());

Protect Backpack routes with Spatie middleware. The package does not automatically lock down your app. Use route middleware:

Route::middleware(['web', 'auth', 'permission:access admin'])
    ->prefix('admin')
    ->group(base_path('routes/backpack/custom.php'));

For finer control inside a CRUD controller:

protected function setup()
{
    parent::setup();

    if (! backpack_user()->can('delete users')) {
        $this->crud->denyAccess('delete');
    }
}

Customize the package CRUDs instead of editing vendor code. Extend the package controller, override setup(), and point your route to your subclass:

namespace App\Http\Controllers\Admin;

use Backpack\PermissionManager\app\Http\Controllers\UserCrudController as BaseUserCrudController;

class UserCrudController extends BaseUserCrudController
{
    public function setup()
    {
        parent::setup();

        $this->crud->addField([
            'name' => 'roles',
            'type' => 'select_multiple',
            'entity' => 'roles',
            'attribute' => 'name',
            'model' => config('permission.models.role'),
        ]);
    }
}

Use Gate::before for super admins. A common pattern is to bypass all checks for a specific role:

Gate::before(function ($user, $ability) {
    return $user->hasRole('super admin') ? true : null;
});

Plan for guards early. If your admin panel uses a guard other than web, create roles and permissions with that guard_name and configure Spatie’s guards array accordingly. The UI will create records using the configured default guard, so a mismatch silently breaks can() checks.

Deployment workflow. After deploying new permissions:

php artisan db:seed --class=PermissionSeeder
php artisan permission:cache-reset

This keeps code-defined permissions and the database in sync, and clears Spatie’s cache across workers.

Gotchas and Tips

• Guard mismatch is the most common failure. Permissions created through the UI default to the configured guard, often web. If your admin area uses a different guard, backpack_user()->can('...') returns false even though the permission exists. Set guard_name explicitly in seeders and verify config/auth.php and config/permission.php.
• Spatie caches permissions aggressively. After changing roles or permissions programmatically—or after deploying seeders—run php artisan permission:cache-reset. In long-running workers or Octane, stale cache can persist until reset.
• The UI can become an uncontrolled source of truth. If admins create permissions freely, staging and production drift. Prefer seeding permission names in code and using the UI mainly for assigning roles/permissions to users.
• Password fields can be double-hashed. Backpack’s password field hashes when configured with 'hash' => true. Do not also hash in a model mutator or you will lock users out.
• Prevent destructive self-management. Add guards so admins cannot delete themselves or remove the last admin role. The package gives you CRUD screens, not these business rules.
• Route and menu collisions are common. The package registers /admin/user, /admin/role, and /admin/permission routes and menu entries. If you already have a user CRUD, customize the route prefix or disable duplicate menu items.
• Deleting roles and permissions needs care. Check pivot cleanup and foreign keys. A role assigned to users may fail to delete or leave orphaned relations depending on your schema.
• Version compatibility matters. Backpack PermissionManager major versions track Backpack CRUD and Spatie versions. Before upgrading Backpack or spatie/laravel-permission, check the package’s composer constraints and retest the UI.
• backpack_user() is not always available. In console commands, queues, and some middleware contexts it returns null. Use explicit guard checks or auth()->user() when outside the admin panel.
• The package is not your authorization layer. It manages records; it does not protect your application routes. Every sensitive route still needs middleware, a Gate check, or a policy.
• Extension points: custom User/Role/Permission models via config/backpack/permissionmanager.php, custom CRUD controllers, custom routes, and Backpack’s denyAccess()/allowAccess() methods inside setup().