Profile Filament Plugin Laravel Package

Getting Started

• Confirm baseline compatibility: Filament ^3.2 (minimum bumped in v0.3.0) and a Laravel version supported by the release you pin. The package is pre-release but described as production-ready; pin a specific version in composer.json because APIs can change without a major bump.
• Install and publish:

  composer require rawilk/profile-filament-plugin
  
  php artisan vendor:publish --tag="profile-filament-migrations"
  php artisan migrate
  
  php artisan vendor:publish --tag="profile-filament-config"
  

• Register the plugin in the panel provider where users should manage their profile:

  use Rawilk\ProfileFilament\ProfileFilamentPlugin;
  
  public function panel(Panel $panel): Panel
  {
      return $panel
          // ...
          ->plugin(
              ProfileFilamentPlugin::make()
          );
  }
  

• First place to look after install: config/profile-filament.php. Review the user model/guard assumptions, enabled features, password rules, MFA/passkey behavior, session management, and email-change settings before exposing the pages.
• First use case: add self-service account management to an existing admin/staff panel. After registration, visit the panel’s profile cluster and verify the base profile page, then exercise password update, MFA enrollment, and active-session listing. Start with profile details and password management, then enable MFA/passkeys and session revocation once auth flows are confirmed.
• For customization or debugging, the current page classes live under the profile cluster namespace: Rawilk\ProfileFilament\Filament\Clusters\Profile\ProfileInfo, Settings, Security, and Sessions. The v0.3.0 release moved these from the older Filament\Pages namespace.

Implementation Patterns

• Register the plugin per panel rather than globally. In multi-panel apps, each panel gets its own profile cluster and routes; the package resolves the plugin from the current panel. Keep each panel’s path/domain and auth guard explicit, and test profile links from every panel.
• Treat the published migrations as application migrations. Review them before running in staging/production, especially if you already have users, sessions, MFA, passkey, or email-verification tables. Reconcile existing schema instead of blindly applying duplicate columns/tables.
• Use the config file as the primary feature toggle layer. Roll out in stages: profile details + password first, then MFA/passkeys, then session management and pending email changes. This keeps auth regressions isolated.
• For password management, prefer config-driven validation rules over editing vendor pages. The package uses a Filament password input component; test password updates against your app’s password broker, remember-me behavior, and session invalidation expectations.
• MFA day-to-day flow: users enroll from the Security page, then complete challenges during login or sudo-protected actions. If you build custom actions that require recent authentication, use the package’s sudo/MFA challenge conventions and verify parameters are passed through to the challenge action. The v0.1.2 release fixed a sudo challenge parameter bug that could bypass sudo mode, so keep that version or newer.
• The package exposes an Mfa service; release notes mention pushChallengedUser. Use service-level calls for programmatic challenge flows rather than duplicating MFA session logic in controllers or Filament actions.
• Session management is exposed through the Sessions page. If your app relies on “log out other devices,” verify your SESSION_DRIVER and session storage support enumeration/revocation. Database sessions are the safest assumption for active-device management; test that revoking other sessions preserves the current session.
• Pending email changes use verification links. Ensure APP_URL, mail configuration, signed URLs, and queue workers are correct. If you customize redirects, account for the InvalidVerificationLinkException::redirectTo signature fix in v0.3.4.
• Passkeys/WebAuthn require a secure context: HTTPS in non-local environments, or localhost in development. Keep the package’s frontend assets and @simplewebauthn/browser expectations aligned with the installed package version; release notes show major JS dependency bumps.
• Since v0.3.0 removed addPage and navigation from the plugin, do not build customization around those old APIs. Use Filament’s native navigation groups/clusters and register custom pages through the panel. For custom profile fields, either extend the cluster page classes where documented or keep an adjacent Filament page/resource and link it from the profile area.
• Add application-level feature tests around the flows you expose: profile update, password change, MFA enrollment/challenge, passkey registration, session revocation, and pending email verification. Use actingAs() with the correct guard and assert redirects/notifications, not just page loads.

Gotchas and Tips

• Pin the package version. It is explicitly pre-release; API and functionality may change without a major version bump. Read the changelog before every upgrade, especially around v0.3.0, which introduced namespace moves and removed old plugin methods.
• v0.3.0 is the main upgrade trap: profile pages moved from Filament\Pages to Filament\Clusters\Profile, addPage/navigation were removed, IsProfilePage was removed, and the old layout component was removed. Any custom code referencing those will break.
• After changing plugin registration or config, clear caches:

  php artisan config:clear
  php artisan route:clear
  php artisan view:clear
  php artisan filament:optimize-clear
  

  In production, rebuild caches and Filament assets (php artisan filament:assets) if styles or components look stale.
• Review migrations in a fresh local database first. Publishing migrations can collide with existing auth/session tables; this is especially likely in mature Laravel apps. Inspect the generated files before running migrate.
• Multi-panel setups need extra testing. If panels use different guards or user models, verify the package config resolves the correct auth user. Test login redirects and pending-email flows per panel; v0.3.2 fixed a null-auth-user redirect issue, but custom guard setups still deserve coverage.
• Sudo mode is security-sensitive. When customizing actions that require recent authentication, verify the challenge action receives all original parameters and that the intended URL is preserved. Test both “recently authenticated” and “needs challenge” paths.
• WebAuthn/passkeys are domain-bound. Changing APP_URL, panel domain, or reverse-proxy scheme can invalidate existing passkeys. Ensure trusted proxies and HTTPS termination are configured correctly before enabling passkeys in production.
• Session management depends on how sessions are stored. If active-device listing appears empty or revocation behaves unexpectedly, check SESSION_DRIVER, session table existence, and whether the package’s session model matches your app. Always verify that “logout other sessions” does not log out the current device.
• Email-change verification links are environment-sensitive. Broken links usually come from wrong APP_URL, proxy headers, mail URL generation, or expired signed URLs. Test with the same host/protocol users will actually use.
• Prefer config and documented extension points over editing vendor files. Because the package is pre-release, wrap custom behavior in your own services/actions and keep package internals at arm’s length. Use the docs site as the source of truth; the README is intentionally minimal.
• For debugging, start with route inspection and logs:

  php artisan route:list --path=profile
  

  Then check Filament panel registration, auth guard resolution, MFA/sudo session state, and storage/logs/laravel.log. If styles are missing after an upgrade, clear Filament caches and republish assets rather than overriding package CSS blindly.