Filament User Manager Laravel Package

Getting Started

filaforge/filament-user-manager v1.0.0 is the first tagged release, so treat this as an initial integration rather than an upgrade. The release notes only link to the changelog, so confirm exact class names, publish tags, and supported Filament version against the installed README/config before wiring it into a production panel.

Minimal path:

1. Require the package at the first stable tag:

   composer require filaforge/filament-user-manager:^1.0
   

2. Publish and inspect config/migrations before running them:

   php artisan vendor:publish --provider="Filaforge\\FilamentUserManager\\FilamentUserManagerServiceProvider"
   

   Use the tags shown by php artisan vendor:publish if the provider tag differs.
3. Review config/filament-user-manager.php for user model, guard, role/permission integration, and table names.
4. Run migrations in a local/staging environment first.
5. Register the plugin in your Filament panel provider, using the plugin class named in the README (commonly something like UserManagerPlugin::make()):

   ->plugin(UserManagerPlugin::make())
   

6. Ensure your User model implements FilamentUser and that canAccessPanel() allows your admin users.
7. Log in with a seeded admin and open the generated Users resource as the first use case: create a user, assign a role/permission, then verify access with that user.

Where to look first: the package README, config/filament-user-manager.php, the plugin service provider, and the published UserResource/pages. Those files will tell you whether the package owns the user CRUD UI, role management, profile editing, or all three.

Implementation Patterns

Use the package as the admin-facing user administration layer, not as a replacement for your application’s domain authorization. Common day-to-day patterns:

• Panel-scoped registration: Register the plugin only on the admin panel. For multi-panel apps, register it per panel and explicitly scope the user model/guard so customer and staff panels do not share the same user list.
• Resource customization: Prefer extending or configuring the provided resource over editing vendor files. Override form/table methods, navigation group, labels, and actions in a subclass or via published config.
• Role/permission workflow: Seed roles and permissions in application seeders, then use the package UI to assign them. Keep policy/gate checks in your app code as the source of truth; the UI should only manage assignments.
• Existing User model: Point the package at your existing App\Models\User and auth guard. If you use Spatie permissions or another authorization layer, confirm the package’s expected contract in config before enabling role management.
• Onboarding/admin bootstrap: Create the first admin via seeder or tinker, then use the package to manage subsequent users. Avoid relying on the UI for the very first admin if panel access depends on a role that does not exist yet.
• Testing: Use your normal factories and actingAs() tests. Add tests for panel access, policy denials, and role assignment changes so package upgrades do not silently widen access.
• Extension points: Subclass resources/pages, publish config, use Filament actions/hooks, and add policies. If the package exposes events or model observers, hook audit logging there rather than in the UI layer.

A practical first workflow: install on a staging panel, create a non-admin user through the UI, assign a limited role, log in as that user, and verify both allowed and denied resources. That catches guard, policy, and panel-access mismatches early.

Gotchas and Tips

• Sparse v1.0.0 notes: The release notes are only a changelog link. Do not assume feature parity with similar packages; verify actual resources, config keys, and publish tags from the installed source.
• Publish before migrate: Inspect migrations and config before running them. Check for table-name conflicts with existing users/roles/permissions tables.
• Guard/model mismatch: Empty user lists, failed role assignment, or “access denied” usually means the panel guard, auth provider, and configured user model do not align.
• Permissions cache: If integrating with a permission package, reset its cache after seeding or changing roles. Stale caches can make UI changes appear ineffective.
• Filament version compatibility: Confirm the package’s composer constraints against your Filament major version. A v1.0.0 package may target a specific Filament generation.
• Clear caches after registration: Run php artisan filament:optimize-clear and php artisan config:clear after changing panel providers or package config.
• Do not edit vendor code: Use published config, resource subclasses, policies, and Filament hooks. Vendor edits will be lost on the next composer update.
• Debug access issues: Use php artisan route:list, check panel access via canAccessPanel(), and log policy/gate denials. For UI issues, inspect the registered resource and its form/table schema.
• Pin the major version: Use ^1.0 and review changelog entries before upgrading. Since this is the first stable tag, future minor releases may still adjust integration details.