Filament Accounts Auth Laravel Package

Getting Started

This release is a platform jump, not a feature drop: the package now targets PHP 8.2+, Laravel 12/13, Livewire 4 (Volt 1.10+), Filament 5, and tomatophp/filament-accounts 5. If your app is still on Filament 3/4 or Livewire 3, stop here — the 1.x line remains on the v3 branch and is the correct pin for older stacks.

1. Confirm the whole matrix before touching composer: php -v, composer show laravel/framework livewire/livewire filament/filament tomatophp/filament-accounts. All five must be on the new majors; a partial upgrade will resolve to a conflict rather than a working install.
2. composer require the package plus tomatophp/filament-accounts:^5 in the same command so the solver sees the pair together.
3. Re-publish the front-end assets — the auth pages load public/auth/build, and stale assets from a previous major are the most common "it installed but looks broken" symptom.
4. Run migrations for the accounts model, then boot the app locally and walk /auth/setup/*. Those routes are only reachable in the local environment or behind the viewAuthSetup gate, so a 404 on staging is expected, not a bug.
5. Look first at the package config (guards, account model, language) and the published language files. Almost every behavioural question in this package is answered by config rather than code.

First real use case: swapping the host app's hand-rolled login/register/reset screens for the package's Volt-powered pages inside a Filament 5 panel, with 2FA challenge handled by the accounts guard.

Implementation Patterns

Treat the setup pages as a provisioning surface. The /auth/setup/* routes are the intended path for creating the first account and seeding auth config. In day-to-day work, gate them explicitly rather than relying on the local environment check — define viewAuthSetup in a service provider and grant it to a named admin or an IP allow-list for staging:

Gate::define('viewAuthSetup', fn (User $user) => $user->hasRole('super-admin'));

Keep the gate closed on production; the environment check alone won't protect you if APP_ENV is misconfigured.

Drive copy through the language config, not the Blade files. Page texts come from the language config with per-locale overrides, which makes multi-language marketing copy a config concern. Publish the lang files, then add a locale-keyed override array per page. This release adds the previously missing phone label on the register page, so if you maintain overrides, diff your files against the shipped ones before assuming your copy is complete.

Wire 2FA against the accounts guard deliberately. The two-factor challenge logs in on the accounts guard using the configured account model. That means config('auth.guards.accounts') and the model referenced in the package config must point at the same class — a mismatch shows up as a successful challenge that leaves the user anonymous on the next request. Verify with a feature test that asserts auth('accounts')->check() after the challenge, not just the redirect.

Publish assets as part of deploy. Because the pages read the published public/auth/build bundle, add a publish step to your deploy script and clear the old directory first. The system-font fallback means a missing bundle degrades quietly rather than erroring — visually wrong, not loudly broken.

Keep Blade Icons explicit in tests. The package no longer replaces the host app's Blade Icons factory in the testing environment. If your suite previously leaned on that, icon assertions may now resolve against your real icon sets. This is a good change; it just may surface latent assumptions.

Gotchas and Tips

• Hard conflict with devdojo/auth. Both claim the Devdojo\Auth namespace, and the release declares the conflict in composer. If you're migrating from the original package, remove it and its published assets/config in the same commit — leaving both installed produces class-resolution errors that look like autoload corruption.
• Not a drop-in for 1.x. The 1.x line stays on the v3 branch. Pin ^1.0 explicitly if you can't move to Filament 5; don't let a floating constraint drag a Filament 3 app onto v5.
• Volt is a hard floor. Livewire 4 alone isn't sufficient — Volt 1.10+ is required. A stale Volt transitive dependency is a plausible source of "works locally, fails in CI" if your lockfiles differ.
• Setup routes 404 outside local. Reach for the viewAuthSetup gate before debugging routing, middleware or panel registration.
• Silent font fallback. No build assets means system fonts, not an exception. Check the public/auth/build manifest exists after every deploy.
• Guard/model drift on 2FA. The challenge authenticates on accounts, not the default guard. Session checks elsewhere in your app that use the web guard will disagree; standardise which guard your app reads.
• Debugging order: config first (auth, package config, language), then published assets, then the gate, then routes. The package is heavily config-driven, so most "broken" reports resolve without touching vendor code.
• Quality signals are good. Pest suite, PHPStan and a Laravel 12/13 CI matrix mean static analysis catches most upgrade breakage before runtime — run phpstan against your own overrides of the package's config and views after upgrading.