Filament Complete User Profile Laravel Package

Getting Started

• Confirm runtime requirements before installing: PHP 8.3+, Laravel 13.x, and Filament >=5.8.3 <6.0.0. If you are on Filament 5.10.x, use v1.2.2+ so email MFA works with Filament’s native provider.
• Install with Composer:

  composer require mortalkiller/filament-complete-user-profile
  

• Register the plugin in the Filament panel provider(s) where users should manage their account:

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

• Publish and review any package config/assets, then run migrations if the package ships profile-related schema changes:

  php artisan vendor:publish --tag="filament-complete-user-profile-config"
  php artisan migrate
  

• First use case: add a complete account area to an existing Filament app panel — profile details, password change, email MFA enrollment, and mobile-friendly account navigation. Verify by logging in as a non-admin test user, opening the profile page, enabling email MFA, and confirming the code email arrives.
• Look first at: the README installation section, the published config file, the plugin class, the profile page class, and the MFA notification class. Those are the main customization points.

Implementation Patterns

• Register per panel deliberately. If you have separate admin and app panels, register the plugin only where end users should see profile/account pages. Avoid exposing account deletion or MFA management on panels where that is not appropriate.
• Keep profile updates on Filament’s form/action stack. Customize the profile form through the package’s config or by extending its page class rather than duplicating profile logic. Preserve unique-email validation and password hashing conventions used by Filament.
• Treat MFA as Filament-native on 5.10+. The package now delegates one-time-code generation, storage, delivery, and verification to Filament’s provider. Your integration should rely on Filament’s MFA APIs and cache-backed storage, not legacy session keys.
• Customize the email, not the mechanism. The package preserves its custom email notification and 60-second resend cooldown. If you need branded MFA emails, override the notification view/class; do not replace Filament’s code storage or verification flow.
• Test the resend cooldown explicitly. Use Laravel time travel or cache manipulation to cross the 60-second boundary, then assert a new code can be requested. This is a common source of flaky tests.
• Use Notification::fake() for feature tests. Assert the package’s MFA notification is sent to the right user and that the code is verified through Filament’s provider. Add a browser test for mobile account navigation if you customize the menu.
• Queue MFA mail in production. The custom notification can be queued; confirm your queue worker and mail transport are configured. In tests, use Notification::fake() or Mail::fake() rather than relying on the default mailer.
• Upgrade with dependencies:

  composer update mortalkiller/filament-complete-user-profile --with-dependencies
  

  Then run your app’s auth/profile/MFA tests against both your current Filament minor and the next one you plan to adopt.

Gotchas and Tips

• Filament 5.10 changed MFA storage. The legacy session-based code storage is gone. If you previously customized MFA by reading session keys, refactor to Filament’s native provider. v1.2.2 fixes this compatibility, but custom code can still bypass it.
• Version constraints are tight. Laravel 13.x and Filament <6.0.0 are enforced. Check composer why-not mortalkiller/filament-complete-user-profile before upgrading Filament or Laravel, and plan for Filament 6 separately.
• The 60-second cooldown is intentional. Automated tests that request multiple codes quickly will fail unless you advance time or clear the relevant cache. Do not disable the cooldown in production just to simplify tests.
• Cache-backed MFA needs a shared cache store. In multi-node deployments, use Redis/database cache rather than array cache so codes generated on one node verify on another.
• Mobile navigation roles changed. Tests and custom selectors should account for both legacy link and newer menuitem accessibility roles. Prefer role-agnostic selectors or assert both where needed.
• Email MFA depends on mail configuration. Check MAIL_* settings, from-address, and queue workers. A missing code is often a mail/queue issue, not an MFA provider issue.
• Use extension points, not vendor edits. Prefer the published config, custom notification class, and page-class extension/override. Vendor edits will be lost on composer update.
• Debugging checklist: confirm the plugin is registered on the correct panel, the user implements Filament’s auth contract, the profile page is reachable by the user’s guard, the cache store is shared, and the MFA notification is actually dispatched. Filament’s panel registration and auth guard mismatches are the most common causes of “page not found” or “MFA not available.”