Filament Multi Guard Laravel Package

Technical Evaluation

Architecture Fit

• Purpose Alignment: The package extends Filament v2 (admin panel) by enabling multi-guard context support, allowing role/policy-based segmentation of resources, pages, and widgets. This aligns well with Laravel-based SaaS/multi-tenant applications requiring granular access control beyond default Filament guards.
• Design Pattern: Leverages Laravel’s guard system (e.g., auth:guard()) and Filament’s context middleware, making it a lightweight extension rather than a full rewrite. Avoids reinventing core auth logic.
• Limitation: Filament v3+ natively supports this, rendering this package legacy-specific. If migrating to v3, this becomes a non-starter.

Integration Feasibility

• Dependencies:
  • Requires Filament v2.x (explicitly incompatible with v3+).
  • Assumes Laravel 8/9 (PHP 8.0+).
  • No hard dependencies on other packages (e.g., Spatie, Nova).
• Hooks/Extensibility:
  • Registers contexts via FilamentMultiGuardServiceProvider (boot method).
  • Supports custom guard names (e.g., admin, tenant-1) and dynamic context resolution.
  • Can be composed with existing auth systems (e.g., Sanctum, Passport) if guards are properly configured.
• Testing: Minimal test coverage in the repo; assumes Filament’s built-in testing utilities (e.g., FilamentTestCase).

Technical Risk

• Deprecation Risk: High—Filament v3+ obsoletes this package. Adoption implies v2 lock-in unless migration is planned.
• Guard Configuration: Requires manual setup of guards in config/auth.php (e.g., multi-guard driver). Misconfiguration could lead to access control gaps.
• Context Isolation: Limited documentation on how contexts interact with middleware (e.g., CORS, rate-limiting). May need custom middleware for full isolation.
• Performance: Overhead from dynamic guard resolution per request; negligible for most use cases but worth benchmarking in high-traffic admin panels.

Key Questions

1. Filament Version: Is the team stuck on v2 (e.g., due to legacy code) or planning a v3 migration? If the latter, this package is not viable.
2. Guard Strategy: How are guards currently managed? Does the team need dynamic tenant/role-based contexts, or is a simpler solution (e.g., Filament’s built-in policies) sufficient?
3. Testing Coverage: Are there existing tests for multi-guard scenarios? If not, how will integration be validated?
4. Long-Term Maintenance: Who will monitor Filament v3 compatibility or fork this package if needed?
5. Alternatives: Could Filament v3’s native features or custom middleware achieve the same goal with lower risk?

Integration Approach

Stack Fit

• Primary Use Case: Ideal for Filament v2-based admin panels needing:
  • Multi-tenancy (e.g., tenant-{id} guards).
  • Role-based segmentation (e.g., admin, editor, viewer contexts).
  • Dynamic resource isolation (e.g., hide widgets/pages based on guard).
• Compatibility:
  • Laravel: Works with Laravel 8/9 (PHP 8.0+). No conflicts with core auth systems if guards are properly configured.
  • Filament: Hard dependency on v2.x. Incompatible with v3+.
  • Other Packages: Agnostic to auth providers (e.g., Sanctum, Passport) as long as guards are registered.
• Anti-Patterns:
  • Avoid using this for user-level permissions (use Filament’s built-in policies instead).
  • Not suitable for public-facing routes (designed for admin panels).

Migration Path

1. Pre-Integration:
   • Audit Filament version: Confirm v2.x usage. If v3+ is in scope, abort and use native features.
   • Guard Setup: Define guards in config/auth.php (e.g., multi-guard driver with custom user providers).
   • Dependency Check: Ensure filament/filament:^2.x is installed.
2. Installation:

   composer require iotronlab/filament-multi-guard
   

   • Publish config (if needed): php artisan vendor:publish --tag="filament-multi-guard-config".
3. Configuration:
   • Register contexts in AppServiceProvider or a dedicated service provider:

     FilamentMultiGuard::context('admin')
         ->resources([PostResource::class])
         ->pages([Dashboard::class]);
     

   • Bind guards to contexts (e.g., via middleware or route groups).
4. Testing:
   • Test context isolation (e.g., verify admin guard sees only PostResource).
   • Validate guard switching (e.g., auth:guard('tenant-1')).
5. Post-Integration:
   • Monitor Filament v3 updates for native alternatives.
   • Document guard-context mapping for onboarding.

Compatibility

• Laravel Features:
  • Works with Laravel’s auth system (guards, providers, policies).
  • Middleware: Can be combined with auth:guard() or custom middleware.
  • Events: No built-in events, but can extend via listeners.
• Filament Features:
  • Supports resources, pages, and widgets per context.
  • No support for plugins: Contexts are global to the Filament instance.
• Edge Cases:
  • Fallback Guard: Define a default guard in config if no context matches.
  • Caching: Context resolution is not cached by default; may need Cache::remember for performance.

Sequencing

1. Phase 1: Proof of Concept
   • Set up a single guard/context (e.g., admin).
   • Test resource/page visibility.
2. Phase 2: Multi-Guard Rollout
   • Add tenant/role-specific contexts (e.g., tenant-1, editor).
   • Implement guard switching logic (e.g., via middleware or API).
3. Phase 3: Polish
   • Add logging for guard resolution failures.
   • Optimize performance if context resolution is slow.
4. Phase 4: Deprecation Planning
   • Track Filament v3 adoption; prepare migration strategy.

Operational Impact

Maintenance

• Vendor Lock-In: High—tied to Filament v2. Future updates depend on:
  • Filament v2 LTS support (if any).
  • Community forks (currently none).
• Dependency Updates:
  • Monitor Filament v2 patches for breaking changes.
  • No auto-updates: Manual testing required for new Laravel/Filament versions.
• Customization:
  • Extensible: Can override context resolution logic.
  • Limited Docs: May require reverse-engineering for advanced use cases.

Support

• Community:
  • Low activity (50 stars, last release 2023-03-01).
  • No official support: Issues may go unanswered.
• Debugging:
  • Basic Logging: Add Log::debug() to context resolution methods.
  • Common Pitfalls:
    • Forgetting to register guards in config/auth.php.
    • Misconfigured guard providers (e.g., wrong user model).
• Fallback:
  • Revert to Filament v3 if possible.
  • Custom Middleware: Implement guard-context logic manually.

Scaling

• Performance:
  • Request Overhead: Guard resolution adds ~1-5ms per request (negligible for most admin panels).
  • Database Load: No direct DB impact, but guard user lookups may scale with tenant count.
• Horizontal Scaling:
  • Stateless: Works in multi-server setups (guards are resolved per-request).
  • Caching: Cache guard resolutions if using dynamic providers (e.g., Cache::remember).
• Load Testing:
  • Test with 100+ concurrent admin users across guards to validate stability.

Failure Modes