Filament User Laravel Package

Getting Started

This package bundles four Filament plugins into a single install: filament-export, filament-impersonate, spatie/laravel-permission, and filament-shield. In practice you're getting an admin panel with table exports, user impersonation, and a full role/permission layer wired into Filament's authorization.

First steps after composer require:

1. Publish and run the Spatie permission migrations:

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

2. Install Shield and generate permissions for everything Filament already knows about:

   php artisan shield:install admin
   php artisan shield:generate --all
   

3. Add the impersonation contract to your User model:

   use STS\FilamentImpersonate\Concerns\Impersonatable;
   
   class User extends Authenticatable implements FilamentUser
   {
       use Impersonatable;
   }
   

Look first at config/filament-shield.php — it controls the super-admin gate, permission naming, and which entities get generated. That file determines almost everything you'll debug later.

Your first useful use case: a UserResource with a roles Select field, ImpersonateAction in the table row actions, and ExportAction in the header. That single screen exercises all four plugins and is the fastest way to confirm the wiring works.

Implementation Patterns

Gate everything through Shield-generated policies. Don't hand-write canViewAny() on resources. Let shield:generate --all produce policies, then attach roles in a seeder:

$admin = Role::create(['name' => 'admin']);
$admin->givePermissionTo(Permission::all());

$editor = Role::create(['name' => 'editor']);
$editor->givePermissionTo(['view_any_user', 'view_user']);

Re-run shield:generate --all any time you add a resource, page, or widget. Treat it as part of your resource scaffolding checklist.

Pair exports with permissions rather than hiding them ad hoc. Export actions respect the resource policy, but if you expose a custom bulk export, gate it explicitly:

Tables\Actions\BulkAction::make('export')
    ->visible(fn () => auth()->user()->can('view_any_order'))

Prefer queued exports for anything user-facing at scale. filament-export supports queued exports; for tables over a few thousand rows, configure the queue connection so the request doesn't time out. Define explicit ExportColumns instead of exporting the whole model — it keeps memory flat and avoids leaking sensitive columns:

ExportColumn::make('email'),
ExportColumn::make('roles.name')->label('Roles'),

Scope impersonation tightly. Add ImpersonateAction only to resources where it makes sense, and guard it with its own permission rather than leaving it available to every admin:

ImpersonateAction::make()->visible(fn () => auth()->user()->hasRole('super_admin'))

Log impersonation start/stop via the plugin's events if you're in a regulated environment.

Combine the pieces into a coherent workflow. A typical day-to-day pattern: Shield gates the resource → the resource's table has an export action → a super-admin can impersonate a problematic user from the same table to reproduce their view. Document that chain for your team; it's the reason these four packages ship together.

Gotchas and Tips

• Permission cache is the #1 source of "it says forbidden but I gave the role". Run php artisan permission:cache-reset (or cache:forget spatie.permission.cache) after seeding or changing roles in tinker.
• Shield's super-admin bypass is a gate, not a role. Users with the configured super-admin role skip policy checks entirely — new resources appear for them without you generating anything. That masks missing permissions during development; always test with a non-super-admin account.
• Regeneration is destructive-ish. shield:generate --all overwrites existing policies unless you pass --ignore-existing-policies. Commit your policies and review the diff after each run.
• Impersonation needs the correct guard. If you use a non-default guard, set filament-impersonate.guard in config. Also confirm Filament::auth() resolves the same guard, or impersonation silently redirects to login.
• Exports load the model unless you tell them not to. Large tables with relationships will blow memory — use ExportColumn definitions and enable queuing (->queue()), and check the failed-jobs table for silently dropped exports.
• Column naming drift breaks Shield. Permissions are generated from resource and field names; renaming a resource orphans old permission rows. Clean up stale permissions or you'll accumulate noise in the role UI.
• Order of operations in fresh installs: permission migrations → Shield install → shield:generate → seed roles. Running the seeder before migration is a common CI failure.
• Debugging tip: php artisan shield:generate --all --panel=admin plus dumping Permission::pluck('name') in tinker tells you instantly whether the problem is generation, caching, or policy resolution.
• Extension points: the Shield config file exposes policy path, permission separator, and custom permission subjects; filament-export exposes a writer/disk config for S3 destinations. Both are worth reading before you fork anything.