Filament User Resource Laravel Package

Getting Started

This package gives you a drop-in user management resource for a Filament panel — user CRUD plus a self-service profile page — so you don't hand-roll the same Resource for every project.

1. Install and publish. composer require rupadana/filament-user-resource, then publish the package config/migrations (php artisan vendor:publish --tag=..., check the README for the exact tags shipped with 1.0.x) and run php artisan migrate. Check what landed in config/ first — the published config is the real API surface of this package, and the toggles there (model class, navigation group, which features are enabled) determine most of its behaviour.
2. Register it on the panel. Add the plugin/resource to your PanelProvider (or let the resource auto-discover, depending on your Filament version). Boot the panel and confirm the "Users" nav item appears before you touch anything else.
3. First use case: replace your hand-written UserResource. Delete or rename the existing one in the same commit — two resources pointing at the same model produce duplicate nav entries and confusing route collisions.
4. Verify the auth guard. Open the profile page as a logged-in non-super-admin. This is where guard/model mismatches surface immediately.

Implementation Patterns

Extend, don't fork. The shipped resource class is meant to be subclassed: create app/Filament/Resources/UserResource.php extending the package class, then override form(), table(), getPages(), or getNavigationGroup() as needed. Upgrades stay painless because you never edit vendor files.

Keep profile and admin separate. The package's profile page operates on auth()->user(); the admin resource operates on arbitrary users. Resist merging them — you'll end up with permission checks scattered through form schema. Apply your UserPolicy to the resource and let the profile page rely on Auth.

Compose with roles, don't replace them. If you use Spatie Permission (or Filament Shield), leave role assignment to a dedicated relation manager / field and let this package own the identity fields (name, email, password, avatar). Trying to make one form own both identity and authorisation is the most common source of sprawl.

Per-panel scoping. In multi-panel apps, register the resource only on the panels that should manage users, and use modifyQueryUsing() for tenant scoping rather than relying on global scopes that will also hit the profile page.

Password handling. Prefer a single dehydrateStateUsing(fn ($state) => Hash::make($state)) on the password field and a ->dehydrated(fn ($state) => filled($state)) so blank-on-edit doesn't wipe credentials. Never let the package hashing and your own hashing both run.

Testing. Because these are Livewire components, livewire(UserResource\Pages\CreateUser::class)->fillForm([...])->call('create') plus a policy assertion covers most regressions; add a test that a non-privileged user gets 403 on the resource index.

Gotchas and Tips

• Published files are snapshots. Config, migrations, and views copied into your app will not pick up upstream fixes. After any patch release (including 1.0.1), diff what you published against the vendor copy — especially if you publish views. Re-publish to a temp dir and diff rather than overwriting blindly.
• This release is undocumented. 1.0.1 ships with only an auto-generated changelog link and no described changes. Treat it as a low-risk patch, but read the compare diff on GitHub before bumping, and pin the exact version in composer.lock so a CI run doesn't silently pull a different patch.
• Duplicate navigation entries. The single most common post-install issue: your old UserResource still exists, or the plugin is registered on two panels.
• Guard mismatches. If your panel uses a non-default guard, the package's model resolution and the profile page's auth() call can disagree; set the model/guard explicitly in config rather than assuming the default.
• Permission cache staleness. After seeding roles or changing policies, run php artisan permission:cache-reset and php artisan optimize:clear — stale caches mimic authorisation bugs.
• Avatar/media disk. Uploads fail silently-ish when APP_URL or the storage symlink is wrong; confirm php artisan storage:link and that the configured disk is public in local dev.
• Extension points to prefer, in order: config toggles → subclass overrides → published views → a full fork. Anything past step two means you've outgrown the package for that project and should own the resource outright.
• Upgrade checklist for 1.0.x: read the compare diff → composer update rupadana/filament-user-resource --with-dependencies → re-diff published assets → clear caches → smoke-test create/edit/profile pages.