Filament Multi Context Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require artificertech/filament-multi-context
   php artisan vendor:publish --provider="ArtificerTech\FilamentMultiContext\FilamentMultiContextServiceProvider" --tag="filament-multi-context-config"
   

   Publish the config file to customize default behavior.

2. Create a Context:

   php artisan make:filament-context [ContextName]
   

   Example: php artisan make:filament-context AdminDashboard

3. Register Context: Add the context to config/filament-multi-context.php under the contexts array:

   'contexts' => [
       'admin' => [
           'class' => \App\FilamentAdmin\FilamentAdminContext::class,
           'label' => 'Admin Panel',
           'icon' => 'heroicon-o-home',
           'active' => true,
       ],
   ],
   

4. First Use Case: Access the new context by navigating to /admin (or your configured path). The context will include its own resources, pages, and widgets, isolated from other contexts.

Implementation Patterns

Usage Patterns

1. Context Isolation:

   • Each context (FilamentTeams, FilamentAdmin, etc.) operates independently with its own:
     • Resources (app/[ContextName]/Resources/).
     • Pages (app/[ContextName]/Pages/).
     • Widgets (app/[ContextName]/Widgets/).
   • Useful for multi-tenant or role-based admin panels (e.g., Admin, TeamLeads, Support).

2. Dynamic Context Switching:

   • Override the FilamentMultiContextServiceProvider's boot() method to dynamically register contexts:

     public function boot()
     {
         $this->registerContexts([
             'admin' => \App\FilamentAdmin\FilamentAdminContext::class,
             'team' => \App\FilamentTeams\FilamentTeamsContext::class,
         ]);
     }
     

3. Shared vs. Isolated Assets:

   • Shared: Place global assets (e.g., app/Providers/FilamentServiceProvider) in the root app/Providers/ to apply across all contexts.
   • Isolated: Keep context-specific assets (e.g., app/FilamentTeams/Resources/UserResource) within the context directory.

4. Middleware Integration:

   • Apply context-specific middleware by extending the context class:

     namespace App\FilamentTeams;
     
     use ArtificerTech\FilamentMultiContext\Contracts\FilamentContext;
     use Illuminate\Support\Facades\Gate;
     
     class FilamentTeamsContext implements FilamentContext
     {
         public function getMiddleware(): array
         {
             return [
                 \App\Http\Middleware\CheckTeamAccess::class,
             ];
         }
     }
     

5. Context-Specific Routes:

   • Use the context() helper to generate URLs for resources/pages within a context:

     route('filament.admin.resources.users.index'); // Admin context
     route('filament.team.resources.projects.index'); // Team context
     

6. Widget and Page Sharing:

   • Reuse widgets/pages across contexts by:
     • Copying files to the target context directory.
     • Using trait-based inheritance (e.g., use \App\Widgets\SharedWidget; in context-specific widgets).

Workflows

1. Multi-Tenant Admin Panels:

   • Register a context per tenant:

     Tenant::all()->each(function ($tenant) {
         $this->registerContexts([
             "tenant-{$tenant->id}" => \App\FilamentTenants\FilamentTenantContext::class,
         ]);
     });
     

2. Role-Based Access:

   • Enable/disable contexts based on user roles:

     'contexts' => [
         'admin' => [
             'class' => \App\FilamentAdmin\FilamentAdminContext::class,
             'active' => auth()->user()->isAdmin(),
         ],
     ],
     

3. Context-Specific Notifications:

   • Override the getNotifications() method in the context class to show context-relevant alerts.

4. Testing:

   • Use actingAs() with context-specific users:

     $this->actingAs($adminUser)
          ->get('/admin/resources/users')
          ->assertStatus(200);
     
     $this->actingAs($teamUser)
          ->get('/team/resources/projects')
          ->assertStatus(200);
     

Gotchas and Tips

Pitfalls

1. Namespace Conflicts:

   • Ensure context class namespaces are unique (e.g., App\FilamentTeams\FilamentTeamsContext vs. App\FilamentAdmin\FilamentAdminContext).
   • Avoid naming conflicts with Filament’s core classes (e.g., don’t name a context Resource).

2. Asset Loading Issues:

   • If widgets/pages fail to load, verify:
     • The context is marked as active in the config.
     • The app/[ContextName] directory exists and is autoloaded (check composer.json).
     • No typos in the context class name in config/filament-multi-context.php.

3. Middleware Overrides:

   • Context-specific middleware may conflict with global Filament middleware. Test thoroughly:

     // Ensure this runs AFTER Filament's middleware in app/Http/Kernel.php
     'web' => [
         // ...
         \App\Http\Middleware\CheckTeamAccess::class,
     ],
     

4. Cached Views:

   • Clear Filament’s view cache after adding new contexts:

     php artisan filament:cache-reset
     

5. Database Seeding:

   • Seeders for context-specific resources should target the correct context:

     public function run()
     {
         $this->call([
             \Database\Seeders\FilamentAdmin\AdminUsersTableSeeder::class,
             \Database\Seeders\FilamentTeams\TeamProjectsTableSeeder::class,
         ]);
     }
     

Debugging

1. Context Not Loading:

   • Check the filament-multi-context log channel for registration errors:

     \Log::channel('filament-multi-context')->debug('Context registered');
     

   • Verify the context appears in the filament-multi-context:contexts config array.

2. Routes Missing:

   • Run php artisan route:list to confirm context routes are registered. If missing, check:
     • The context’s getRoutes() method (if overridden).
     • The filament-multi-context service provider is registered in config/app.php.

3. Blade Template Errors:

   • Ensure context-specific Blade files (e.g., resources/views/filament/[context]/...) are properly namespaced:

     @extends('filament::base')
     @section('title', __('Filament Teams'))
     

Tips

1. Context-Specific Config:

   • Use the getConfig() method in the context class to override Filament settings:

     public function getConfig(): array
     {
         return [
             'panel' => [
                 'path' => 'team',
                 'brandName' => 'Team Portal',
             ],
         ];
     }
     

2. Dynamic Context Registration:

   • Register contexts programmatically (e.g., after authentication):

     event(Registered::class, function (Registered $event) {
         if ($event->user->isTeamLead()) {
             app(\ArtificerTech\FilamentMultiContext\FilamentMultiContextServiceProvider::class)
                 ->registerContexts([
                     'team-lead' => \App\FilamentTeamLeads\FilamentTeamLeadsContext::class,
                 ]);
         }
     });
     

3. Shared Authentication:

   • Reuse the same auth system across contexts by extending the context’s getAuthentication() method:

     public function getAuthentication(): array
     {
         return [
             \App\Providers\FilamentAuthProvider::class,
         ];
     }
     

4. Performance:

   • Lazy-load contexts by deferring registration until the first request:

     public function boot()
     {
         if (app()->runningInConsole()) {
             return;
         }
         $this->registerContexts([...]);
     }
     

5. Extending the Package:

   • Add custom context types by publishing and modifying the filament-multi-context config:

     'context_types' => [
         'default' => \ArtificerTech\FilamentMultiContext\Contracts\FilamentContext::class,
         'tenant' => \App\Contracts\TenantFilamentContext::class,
     ],