Filament User Profile Laravel Package

Getting Started

This release (v4.1.0) is almost entirely maintenance, but it ships one user-facing feature: the icons used by the profile page are now exposed as Filament icon aliases, so you can swap them without forking the package.

Minimum path to a working profile page:

1. Install and publish config:

   composer require happenv-com/filament-user-profile
   php artisan vendor:publish --tag="filament-user-profile-config"
   

2. If the package ships its own migrations (avatar column, etc.), publish and run them — check vendor/happenv-com/filament-user-profile/database/migrations first; if your users table already has the columns you need, skip this.
3. Register the plugin on the panel where users should be able to edit their profile:

   public function panel(Panel $panel): Panel
   {
       return $panel
           ->plugin(FilamentUserProfilePlugin::make());
   }
   

4. Log in and hit /admin/profile (or whatever prefix your panel uses).

First use case: replace Filament's bare-bones profile page with one that handles avatar upload, password change, and account deletion in a single form. If you're already on Filament's built-in ->profile(), this is a drop-in upgrade in capability — but decide deliberately whether you keep both, since two "Profile" entries in the user menu is confusing.

Implementation Patterns

Overriding icons (new in 4.1). The hardcoded save/avatar/password icons are now registered as aliases. Register yours in a service provider's boot():

use Filament\Support\Facades\FilamentIcon;

public function boot(): void
{
    FilamentIcon::register([
        // exact alias keys vary — grep the package for FilamentIcon::register
        'filament-user-profile::profile.actions.save' => 'lucide-check',
    ]);
}

To find the real alias strings, run:

grep -rn "FilamentIcon" vendor/happenv-com/filament-user-profile/src

The package's own register() call is the authoritative list — don't guess at key names, they're plain strings and a typo fails silently back to the default icon.

Multi-panel setups. Instantiate the plugin per panel rather than globally, so a customer-facing panel and an admin panel can have different profile behaviour. Plugin config is per-instance, so ->plugin(FilamentUserProfilePlugin::make()->something(...)) in each PanelProvider.

Theming consistency. If you've standardized on one icon set (Lucide, Tabler, etc.), this release is the moment to align this package with the rest of your UI. Do it once in a shared service provider alongside your other FilamentIcon::register() calls, not scattered across panel providers.

Testing. Because this is a Livewire page, a smoke test is cheap and catches broken upgrades:

livewire(EditProfile::class)->assertOk()->assertFormExists();

Add it now — you'll want it when v5 lands.

Upgrade hygiene. This is a patch-level bump with no API breaks. Bump in composer.json, run php artisan optimize:clear, and smoke-test the profile page. No migration or config republish required.

Gotchas and Tips

• Alias typos are silent. FilamentIcon::register() with an unknown key doesn't throw — you just get the old icon and wonder why your override did nothing. Confirm by setting a deliberately absurd icon first.
• Icon caches. Filament caches panel components and icons in production. After registering new aliases, php artisan filament:cache-components (or a full optimize:clear) before concluding it didn't work.
• Custom icon sets need assets. Aliasing to a set you haven't installed/published will render blanks. Run php artisan filament:assets after adding one.
• Verify Filament major compatibility. A v4.x plugin line almost certainly targets Filament v4. If you're still on Filament v3, check the constraint before upgrading — this is the most likely source of a broken install, not anything in the changelog.
• Avatar storage. Whatever disk the config points at needs php artisan storage:link and correct APP_URL; avatar uploads are the #1 "it works locally, broken in prod" issue with profile plugins.
• The rest of the changelog is maintainer-side. The Dependabot bumps (actions/checkout 4→7, laravel-pint-action 2.3→2.6), SHA-pinned Actions, Copilot review, the security policy, and the Laravel Moat config have zero runtime impact on consumers. The actions/checkout 4→7 jump is three majors and is worth knowing about only if you maintain a fork.
• Young package, thin surface. The added SECURITY.md and pinned CI are good hygiene signals, but the project is small and bus-factor-one. Pin the constraint (^4.1) and keep the smoke test above so a future release can't silently break your profile page.
• Extension point to watch. Icon aliases are a small commitment to themability; if you need deeper customization (extra form fields, custom save logic), check whether the plugin exposes a form-schema or action hook before reaching for a subclass — page classes in Filament plugins are frequently final or not intended for extension.