Filament Accounts Laravel Package

Technical Evaluation

Architecture Fit

• Multi-Account Management: Still consolidates accounts into a single Eloquent table with Filament-driven admin management, which remains a strong fit for SaaS, marketplaces, and tenant/role-scoped workflows. The single-table design trade-offs (table bloat, slower joins at scale) are unchanged.
• Multi-Auth Integration: Sanctum, Passport, and Jetstream support is preserved, and the release adds documented auth.php guard examples plus useTypes() and impersonation patterns — measurably reducing the "custom auth wiring" gap previously flagged for OAuth/SSO extension.
• Filament Dependency (now v5): Coupling has tightened. The package now requires Filament v5 / Livewire 4, a materially larger admin-panel footprint than the previous v3 baseline. Projects on Filament v3 or v4 cannot adopt this line without a Filament upgrade. The v4 maintenance branch (see below) is the escape hatch for teams that can't move yet.
• New Hard Dependencies: v5.0.0 introduces tomatophp/filament-types ^5.0.1 as a required dependency, and maatwebsite/excel ^3.1.64 || ^4.0 for export/import. This expands the transitive dependency surface — worth evaluating alongside the package itself.
• Single-Table Design: Unchanged; still appropriate for read-heavy datasets with composite indexes on account_type / status, and still a scalability watch-item beyond ~100K accounts.

Integration Feasibility

• Laravel Ecosystem Compatibility: Baseline shifts from Laravel 10/11 to Laravel 12/13. Laravel 9.x and 10.x are now effectively unsupported by this release line.
• Filament Versioning: Requires Filament v5 (with Livewire 4). If you are on v3, this is a two-major-version jump; if on v4, it's one. Filament v4 releases continue on the v4 branch, which is important for phased adopters.
• PHP Requirement: Minimum is now PHP 8.2+ (previously 8.1+). Confirm CI runners and container images.
• Database Schema: Migration-friendly as before; still assumes a relatively fresh Laravel setup and requires schema refactoring when consolidating legacy multi-tenant tables.
• Export/Import: Now first-class via maatwebsite/excel, including compatibility with Excel v4 and the Filament v5 schema() API. This was previously a "would need extension" gap.
• Auth Plugins / Third-Party: Stripe/Paddle/PayPal subscriptions unchanged; custom gateways still need extension work.

Technical Risk

• Filament Lock-in (elevated): Now pinned to Filament v5 + Livewire 4. Migration to Nova/Backpack or a custom admin remains costly, and the upgrade cost from v3 is now larger.
• Version Jump: This is a major-version breaking release (v5 line). Composer constraints, Filament plugin registrations, and any overrides of package views/resources will likely need adjustment. The v4 branch exists, so teams must explicitly choose a track.
• New Dependency Risk: tomatophp/filament-types and maatwebsite/excel become transitive liabilities — a bug or breaking change in either propagates to this package.
• Performance at Scale: Unchanged N+1 / single-table filtering concerns; indexing strategy still required. getUrl() signature fix (#20) should reduce one class of admin routing bugs.
• Customization Gaps: Still requires middleware/policy overrides for account hierarchies and dynamic permissions.
• Test Confidence (improved): The extended Pest suite now covers the account types page, install command, export/import, and every plugin feature — a meaningful risk reduction versus the previous assessment's "limited adoption" note.

Key Questions

1. What Filament version is the project on? If v3, this is a two-major upgrade; if v4, decide between upgrading Filament or tracking the v4 maintenance branch of this package.
2. Is the stack on Laravel 12/13 and PHP 8.2+? If not, this release is off the table until that migration completes.
3. Are you comfortable adding tomatophp/filament-types and maatwebsite/excel? Both are now hard requirements.
4. What's the expected scale? For >50K accounts, assess partitioning/read replicas; unchanged from before.
5. Are existing auth systems supported? Sanctum/Passport/Jetstream are fine; Auth0/Keycloak still require adapter work.
6. How much of the existing package surface is overridden? v5 breaking changes will surface wherever views, resources, or actions were customized.

Integration Approach

Stack Fit

• Laravel Core: Native auth/middleware/Eloquent integration unchanged; minimum Laravel is now 12.
• Filament Admin: Now requires Filament v5 (Livewire 4). Pre-built CRUD/search/filter panels remain the value proposition; the cost of entry scales with the Filament upgrade.
• Auth Drivers: Sanctum, Passport, Jetstream supported; new documented auth.php guard example and impersonation guidance reduce integration guesswork.
• Database: MySQL/PostgreSQL via Laravel; SQLite may need tuning at volume.
• New Required Peer: tomatophp/filament-types ^5.0.1 (default customer/account types are auto-seeded the first time the Accounts Types page is opened — a small but welcome onboarding improvement).

Migration Path

1. Track Decision:
   • Choose between v5 (Filament v5 / Laravel 12+) and the v4 maintenance branch (Filament v4). The branch strategy in this release formalizes that choice.
2. Assessment Phase:
   • Audit Laravel, Filament, Livewire, PHP versions against the new floor (Laravel 12, Filament v5, Livewire 4, PHP 8.2).
   • Audit existing overrides of package views/resources; these are the likeliest breakage points in a major bump.
3. Dependency Pre-Flight:
   • Verify tomatophp/filament-types ^5.0.1 and maatwebsite/excel ^3.1.64 || ^4.0 resolve cleanly against your lockfile.
4. Pilot Implementation:
   • Staging with a subset of accounts; exercise account switching, impersonation (newly documented), role assignment, and export/import via the v5 schema() API.
5. Phased Rollout:
   • Upgrade Filament first in isolation, then the package, then re-register resources.
   • Migrate non-critical accounts before critical tenants; keep legacy UI in parallel until verification is complete.

Compatibility

• Laravel: 12.x / 13.x (was 10.x / 11.x). Laravel 9/10 are no longer supported by the v5 line.
• Filament: v5 required (Livewire 4). Filament v4 is supported only via the v4 branch of this package.
• PHP: 8.2+ minimum.
• Dependencies:
  • tomatofy/filament-types ^5.0.1 — new hard requirement; align versions with Filament.
  • maatwebsite/excel ^3.1.64 || ^4.0 — new hard requirement for export/import.
  • Sanctum/Passport/Jetstream conflicts still need verification.

Sequencing

1. Toolchain Upgrade: Move to Laravel 12+, Filament v5, Livewire 4, PHP 8.2 before installing the package line.
2. Install:

   composer require tomatophp/filament-accounts
   

   (Pulls in filament-types and maatwebsite/excel transitively.)
3. Publish & Migrate: Publish config/migrations and run php artisan migrate; let the Accounts Types page seed default customer/account types on first open.
4. Auth Wiring: Apply the documented auth.php guard example and useTypes() pattern; review impersonation docs.
5. Export / Import: Validate actions against Filament v5 schema() and confirm Excel 3 vs 4 line.
6. Test: Load-test with 10K+ accounts; run the extended Pest suite in CI as a baseline health check.

Operational Impact

Maintenance

• Branch Strategy: Two active lines—main (v5 / Filament v5 / Laravel 12+) and v4 (Filament v4). Pin accordingly and plan a v4 → v5 cutover before the v4 line ages out.
• Breakage Surface: v5 is a major release; expect view/resource overrides to need revalidation. Use Dependabot/semver monitoring as before.
• Transitive Maintenance: Track tomatophp/filament-types and maatwebsite/excel release notes — regressions there now affect this package.
• Test Coverage: Extended Pest suite is a maintenance win — run it in CI to catch transitive breakage early.

Support

• Community: Adoption signal still modest, but the expanded test suite and clearer docs (auth guard, useTypes(), impersonation) improve the self-serve story.
• Debugging: Laravel Debugbar + Filament logs remain the toolkit; the getUrl() fix (#20) removes a known class of admin-routing confusion.
• Fallbacks: Keep legacy auth routes during migration; keep a documented pin to the last v4-branch release as a rollback target.

Scaling

• Database: Same guidance — composite indexes on identifier/type/status, read replicas beyond ~10K, archiving via soft deletes.
• Caching: Cache account metadata; lean on Filament caching for admin performance (note Livewire 4 may shift some caching behavior — validate).
• Horizontal Scaling: Queue account tasks, Redis sessions; no change in principle.

Failure Modes