Filament Subtenant Scope Laravel Package

Technical Evaluation

Architecture Fit

• Multi-Tenancy Extension: The package elegantly extends Filament’s built-in tenancy by introducing a second-level scope (e.g., regions, branches) without requiring per-resource modifications. This aligns well with SaaS platforms needing hierarchical filtering (e.g., "Company → Service Area").
• Global Query Scoping: Leverages Laravel’s global query scopes to filter all Eloquent queries across the panel, reducing boilerplate and ensuring consistency. This is a high-leverage pattern for TPMs managing complex data silos.
• Filament Ecosystem Synergy: Designed for Filament’s architecture (v4/v5), integrating seamlessly with its topnav, resources, widgets, and global search. The package’s reliance on Filament’s existing abstractions (e.g., PanelServiceProvider) minimizes architectural drift.

Integration Feasibility

• Low-Coupling Design: The package requires only:
  1. A trait (HasSubtenantScope) for models.
  2. A scopes() array in the Filament panel configuration. This minimal surface area reduces integration risk and aligns with Laravel’s "convention over configuration" philosophy.
• URL-Based Persistence: Sub-tenant selection persists via query parameters (e.g., ?subtenant=nyc), enabling:
  • Shareable links.
  • Bookmarking.
  • Cross-session consistency.
• Blade/Asset Integration: Requires a Vite theme update to compile plugin styles, but this is a one-time setup. The @source directive is a standard Filament pattern, so no custom build tools are needed.

Technical Risk

• Filament Version Lock: Hard dependency on Filament v4/v5 and Livewire v3/v4. If the project uses an older version or plans to upgrade/downgrade, this could introduce breaking changes or require forks.
• Query Scope Conflicts: Global scopes may interfere with existing query logic (e.g., soft deletes, custom scopes). Testing is required to ensure no unintended filtering (e.g., ->whereNull('deleted_at') being overridden).
• Performance Impact: Global scopes apply across all queries, which could bloat queries if not optimized. Mitigation: Ensure sub-tenant relationships are indexed (e.g., subtenant_id on all scoped models).
• UI/UX Edge Cases: The topnav dropdown’s behavior (e.g., default selection, empty-state handling) must align with the app’s design system. The package provides limited customization out of the box.

Key Questions for the TPM

1. Tenancy Strategy:
   • How does this package fit into the existing tenancy model? Is it replacing, extending, or parallel to Filament’s built-in tenancy?
   • Are there conflicts with other global scopes (e.g., SoftDeletes, Filterable)?
2. Data Model:
   • Which models will use sub-tenant scoping? Are they all related to the same subtenant table, or are there multiple sub-tenant types (e.g., "region" vs. "department")?
   • How are sub-tenants assigned to users? Is this handled via middleware or a separate package?
3. Performance:
   • What’s the expected query volume? Could global scopes lead to N+1 issues or slow down the panel?
   • Are there indexes on subtenant_id columns in all scoped tables?
4. Customization:
   • Does the topnav dropdown need branding (e.g., icons, labels) or custom logic (e.g., dynamic options)?
   • Can the scope persistence (URL params) be disabled for certain routes?
5. Testing:
   • How will cross-subtenant data leaks be prevented (e.g., a user in "NYC" accidentally seeing "LA" data)?
   • Are there unit/integration tests for the package’s global scope behavior?
6. Future-Proofing:
   • What’s the upgrade path if Filament v6 breaks compatibility?
   • Could this package be forked to add missing features (e.g., nested sub-tenants)?

Integration Approach

Stack Fit

• Filament v4/v5: Native compatibility with Filament’s panel system, resources, and widgets. The package extends Filament’s PanelServiceProvider, so integration is stack-aligned.
• Laravel Eloquent: Relies on global query scopes, which are a first-class Laravel feature. No custom ORM workarounds needed.
• Livewire: Uses Livewire’s request handling for URL-based persistence, so no additional frontend framework (e.g., Inertia, Alpine) is required.
• Vite: Requires CSS asset compilation, but this is a standard Filament workflow (no custom tooling).

Migration Path

1. Prerequisites:
   • Upgrade to PHP 8.2+, Filament v4/v5, and Livewire v3/v4 if not already compliant.
   • Ensure all scoped models have a subtenant_id column (or equivalent).
2. Installation:
   • Composer install: composer require leek/filament-subtenant-scope.
   • Update Vite theme with @source directive (one-time change).
   • Rebuild assets: npm run dev or npm run build.
3. Configuration:
   • Add the HasSubtenantScope trait to models requiring sub-tenant filtering.
   • Configure the panel’s scopes() array in PanelServiceProvider:

     ->scopes([
         'regions' => Region::class,
         'departments' => Department::class,
     ]);
     

4. Testing:
   • Verify the topnav dropdown appears in the panel.
   • Test URL persistence (e.g., ?subtenant=1).
   • Confirm all resources/widgets respect the scope (no data leaks).
5. Rollout:
   • Start with a non-critical panel for validation.
   • Monitor query performance and user adoption.

Compatibility

• Filament Plugins: May conflict with other plugins using global scopes or topnav modifications. Test with:
  • Filament Spatie Tenant (if using multi-tenancy).
  • Filament Widgets/Resources that apply custom query logic.
• Custom Middleware: If the app uses middleware to set tenancy, ensure it coexists with the sub-tenant scope (e.g., Company → Subtenant hierarchy).
• Legacy Code: If models already have custom scopes, merge them with the package’s applySubtenantScope logic.

Sequencing

1. Phase 1: Setup
   • Install package, update Vite, configure panel.
   • Add subtenant_id to models (if missing).
2. Phase 2: Core Integration
   • Apply HasSubtenantScope to pilot models.
   • Test global scoping in a sandbox panel.
3. Phase 3: Validation
   • End-to-end testing with real data.
   • Performance benchmarking (query times, memory usage).
4. Phase 4: Rollout
   • Deploy to staging, then production.
   • Monitor for data leaks or scope conflicts.

Operational Impact

Maintenance

• Dependency Management:
  • The package is MIT-licensed and actively maintained (last release: 2026-05-02). However, Filament upgrades may require re-testing.
  • No vendor lock-in: The codebase is small and self-contained, making forks or replacements feasible.
• Customization Overrides:
  • The topnav dropdown can be extended via Blade templates or JavaScript.
  • Global scope logic can be overridden by publishing and modifying the package’s config.
• Documentation:
  • The README is clear but lacks advanced use cases (e.g., nested sub-tenants, dynamic options). Internal docs may be needed for the team.

Support

• Troubleshooting:
  • Common issues likely include:
    • Scope not applying: Check scopes() array configuration and model traits.
    • URL params not persisting: Verify Livewire’s wire:model or Filament’s request handling.
    • Performance degradation: Profile queries with tntsearch/laravel-scout-tnt or Laravel Debugbar.
  • Debugging Tools:
    • Use dd($query->getQueryLog()) to inspect scoped queries.
    • Filament’s debug() helper to inspect panel state.
• Community:
  • Low community activity (25 stars, no dependents). Support may require self-service or direct outreach to the maintainer.

Scaling

• Performance:
  • Global scopes apply to every query, so indexing subtenant_id is critical.
  • For **