Filament Accounts Laravel Package

Getting Started

Minimal Setup

1. Check your stack first. v5 requires PHP 8.2+, Laravel 12/13, Filament v5 and Livewire 4. If you are still on Filament v4, do not upgrade — stay on the v4 branch (4.x releases).

2. Installation

   composer require tomatophp/filament-accounts
   

   This pulls in tomatophp/filament-types ^5.0.1 (account types) and maatwebsite/excel (^3.1.64 or ^4.0).

3. Publish and migrate

   php artisan vendor:publish --tag="filament-accounts-config"
   php artisan vendor:publish --tag="filament-accounts-migrations"
   php artisan migrate
   

   Or run the package install command shipped with the plugin, which handles publishing + migrations for you.

4. Register the plugin in your panel provider:

   public function panel(Panel $panel): Panel
   {
       return $panel->plugins([
           \TomatoPHP\FilamentAccounts\FilamentAccountsPlugin::make(),
       ]);
   }
   

5. Configure guards — the README ships an auth.php guard example. Point each guard at its model/guard pair before touching the UI.

Where to Look First

• config/filament-accounts.php for feature toggles (types, impersonation, import/export).
• config/auth.php for the guard setup the plugin expects.
• The Accounts Types page in the panel — on first open it seeds the default customer/account types for you, so you get a working taxonomy without writing seeders.

First Use Case

Open /admin/accounts, let the Accounts Types page generate the defaults, create one account per guard, then verify you can switch between them. That single flow exercises guards, types and the panel integration end to end.

Implementation Patterns

Enabling Account Types

Types are opt-in via the config and the useTypes() plugin method:

$panel->plugins([
    \TomatoPHP\FilamentAccounts\FilamentAccountsPlugin::make()
        ->useTypes(),
]);

Without useTypes(), accounts are flat and the Types page adds no value. Decide this before seeding production data.

First-Run Type Bootstrap

The Accounts Types page creates the default customer/account types the first time it's opened. In CI or fresh installs where nobody visits that page, seed the types explicitly so factories, imports and tests don't hit an empty type table.

Import / Export

The Excel actions are first-class and now support maatwebsite/excel 4.x (3.1.64+ also supported). Typical workflow:

1. Export existing accounts to get the exact column layout.
2. Edit in a spreadsheet, keeping type/guard identifiers unchanged.
3. Re-import.

Because actions were rebuilt on the Filament v5 schema() API, any custom action you wrote against v4 form arrays must be migrated.

Impersonation

The plugin exposes impersonation (documented in the README). Use it for support workflows rather than handing out guard credentials — combined with a permission check, it keeps the audit trail on the original admin account.

Multi-Guard Accounts

One account record can be reachable from several guards. Keep guard selection in config/auth.php and config/filament-accounts.php — not in ad-hoc middleware — so the panel, policies and impersonation all agree on which guard is active.

Gotchas and Tips

Upgrading from 4.x

This is a major release:

• Filament v5 + Livewire 4 are hard requirements; the whole panel must move first.
• tomatophp/filament-types must be ^5.0.1 — an older filament-types will block the install.
• maatwebsite/excel must be ^3.1.64 or ^4.0.
• Any custom export/import action built on the v4 form API needs rewriting to schema().
• If you can't move to Filament v5 yet, pin the v4 branch. Don't try to mix.

getUrl() signature

AccountTypes::getUrl() now matches the Filament page signature (fix #20). If you overrode or called it in a custom page/navigation entry, re-check the arguments — a mismatch surfaces as a TypeError, not a friendly error.

"Account column works when no panel is being served"

This was a real breakage for table columns rendered outside a panel context (exports, custom Livewire components, notifications). If you had a workaround guarding Filament::getCurrentPanel(), you can drop it — but verify the column still renders in your non-panel contexts after upgrading.

Caching

Config/guard changes and new plugin features routinely look "broken" until caches clear:

php artisan optimize:clear
composer dump-autoload

After a major version bump, also re-publish config and diff it against your existing file — new keys in v5 won't exist in an old published config.

Debugging

• Tinker is the fastest way to confirm an account's types/guards are actually persisted rather than just present in the form state.
• If the plugin doesn't appear in the panel, check the plugin is registered and that filament-types resolved to ^5.0.1 (composer show tomatophp/filament-types).
• The extended Pest suite in the package covers account types, install command, export/import and each plugin feature — mirror those tests rather than writing your own assertions from scratch.

Extension Points

• Publish and override the package views/translations for panel-specific wording.
• Prefer config toggles (useTypes(), impersonation, import/export) over subclassing the plugin — the v5 rewrite touched the action layer, so subclassed actions are the most likely thing to break on the next major.
• Keep custom account columns panel-independent so they survive upgrades to the "no panel served" path.