Filament Saas Laravel Package

Getting Started

Minimal Setup

1. Install the package:

   composer require a2insights/filament-saas
   

2. Publish migrations, config, and views:

   php artisan vendor:publish --tag="filament-saas-migrations"
   php artisan vendor:publish --tag="filament-saas-config"
   php artisan vendor:publish --tag="filament-saas-views"
   

3. Run migrations:

   php artisan migrate
   

First Use Case: Quick SaaS Admin Panel

• Register the SaaS admin panel in app/Providers/Filament/AdminPanelProvider.php:

  public function panel(Panel $panel): Panel
  {
      return $panel
          ->default()
          ->id('admin')
          ->path('admin')
          ->login()
          ->registration()
          ->passwordReset()
          ->emailVerification()
          ->tenancy(); // Enable multi-tenancy
  }
  

• Access the admin panel at /admin to manage tenants, users, and features.

Implementation Patterns

Core Workflows

1. Multi-Tenancy Management

   • Use FilamentSaas\Tenants\TenantsTable to list and manage tenants.
   • Customize tenant creation via FilamentSaas\Tenants\CreateTenant form.
   • Override tenant logic in app/Providers/FilamentSaasServiceProvider.php:

     public function boot(): void
     {
         Tenant::created(function (Tenant $tenant) {
             // Custom logic on tenant creation
         });
     }
     

2. Feature Flags

   • Enable/disable features for tenants via FilamentSaas\Features\FeaturesTable.
   • Toggle features programmatically:

     use FilamentSaas\Features\Feature;
     
     Feature::toggle('analytics', true, $tenant);
     

3. Subscription Management

   • Integrate with Stripe or other payment gateways using FilamentSaas\Subscriptions\SubscriptionsTable.
   • Extend subscription logic in app/Models/Subscription.php:

     public function handleWebhook($event, $payload)
     {
         // Custom webhook handling
     }
     

4. Customizing Views

   • Override Blade views in resources/views/vendor/filament-saas/.
   • Example: Modify the tenant dashboard:

     @extends('filament-saas::tenants.dashboard')
     @section('content')
         {{-- Custom content --}}
     @endsection
     

Integration Tips

• Filament Widgets: Add custom widgets to the dashboard:

  public function getWidgets(): array
  {
      return [
          StatsOverview::class,
          RecentTenants::class,
          // Custom widget
          CustomWidget::class,
      ];
  }
  

• API Routes: Register SaaS-specific API routes in routes/api.php:

  Route::middleware('auth:sanctum')->group(function () {
      Route::apiResource('tenants', TenantController::class);
      Route::post('tenants/{tenant}/features', [FeatureController::class, 'toggle']);
  });
  

Gotchas and Tips

Pitfalls

1. Namespace Conflicts

   • Ensure your app’s namespace matches the package’s expectations (e.g., App\Models\Tenant vs. FilamentSaas\Models\Tenant).
   • Fix by aliasing models in config/filament-saas.php:

     'models' => [
         'tenant' => App\Models\Tenant::class,
     ],
     

2. Migration Issues

   • If migrations fail, check for duplicate table names (e.g., tenants vs. filament_tenants).
   • Solution: Rename tables in database/migrations/ or use --force with caution.

3. Tenancy Scope Misconfiguration

   • Forgetting to scope queries to the current tenant can cause data leaks:

     // Wrong: Leaks data across tenants
     Tenant::all();
     
     // Correct: Scoped to current tenant
     Tenant::forCurrentTenant()->get();
     

4. Feature Flag Caching

   • Features may not update immediately due to caching. Clear the cache after toggling:

     php artisan cache:clear
     

Debugging Tips

• Log Tenant Switches: Enable debug logs for tenant switching:

  config(['filament-saas.debug' => true]);
  

• Check Middleware: Ensure TenantMiddleware is registered in app/Http/Kernel.php:

  protected $middlewareGroups = [
      'web' => [
          // ...
          \FilamentSaas\Http\Middleware\TenantMiddleware::class,
      ],
  ];
  

Extension Points

1. Custom Tenant Fields

   • Extend the Tenant model and update the form:

     use FilamentSaas\Forms\Components\TenantFields;
     
     TenantFields::make()
         ->schema([
             // Default fields
             TenantFields::make()->schema(),
             // Custom field
             TextInput::make('custom_field')->required(),
         ]);
     

2. Webhook Handlers

   • Override subscription webhook handling:

     public function handleWebhook($event, $payload)
     {
         if ($event === 'invoice.payment_succeeded') {
             // Custom logic (e.g., grant features)
             Feature::toggle('premium', true, $this->tenant);
         }
     }
     

3. Localization

   • Publish translations and customize language files:

   php artisan vendor:publish --tag="filament-saas-translations"
   

   • Edit resources/lang/en/filament-saas.php for translations.

4. Testing

   • Use TenancyTestingTrait for tenant-aware tests:

     use FilamentSaas\Testing\TenancyTestingTrait;
     
     class TenantTest extends TestCase
     {
         use TenancyTestingTrait;
     
         public function test_tenant_creation()
         {
             $this->actingAsAdmin();
             $this->createTenant(['name' => 'Test Tenant']);
             $this->assertDatabaseHas('tenants', ['name' => 'Test Tenant']);
         }
     }