Multi-tenancy con Filament 5: un pannello, più aziende

Il problema della multi-tenancy nello sviluppo web

Quando lo stesso applicativo deve servire più aziende o clienti, ogni tenant deve vedere solo i propri dati, avere i propri utenti e potenzialmente un branding diverso. Costruire questa separazione da zero è complesso, soggetto a errori di sicurezza e richiede un'architettura pensata fin dal primo giorno. Un errore nello scope delle query significa che un'azienda vede i dati di un'altra — uno scenario inaccettabile.

Il problema non è solo tecnico: è anche organizzativo. Ogni tenant può avere esigenze diverse in termini di permessi, workflow e personalizzazione dell'interfaccia. Gestire questa variabilità senza che il codice diventi un groviglio di if-else è una sfida architetturale seria.

Come Filament 5 risolve la multi-tenancy

Filament 5 ha il supporto multi-tenancy integrato nel core del framework, non come plugin esterno. Ogni panel può essere configurato con un tenant model — tipicamente Team, Organization o Company — e tutte le query vengono automaticamente filtrate per il tenant attivo. Non serve aggiungere where manuali in ogni query: Filament applica il filtro a livello globale.

L'implementazione si basa su un concetto semplice: l'utente appartiene a uno o più tenant tramite una relazione Eloquent, e il pannello filtra tutto in base al tenant selezionato. Il cambio di tenant avviene tramite un menu nel pannello, senza logout e senza perdere il contesto di navigazione.

Cosa si ottiene con la multi-tenancy di Filament

• Scope automatico su tutte le query — ogni Resource, ogni widget, ogni relazione viene automaticamente filtrata per il tenant attivo. Non serve ricordare di aggiungere il filtro: Filament lo fa per te
• Switch tenant senza logout — l'utente che appartiene a più organizzazioni passa dall'una all'altra con un click, mantenendo la sessione attiva
• Registrazione tenant con onboarding — flusso di creazione nuovo tenant personalizzabile con wizard multi-step per raccogliere i dati iniziali
• Permessi per tenant — lo stesso utente può avere ruoli diversi in organizzazioni diverse. Admin in un'azienda, viewer in un'altra
• Branding per tenant — logo, colori, nome e favicon personalizzati per ogni tenant, senza deployment separati
• Billing e subscription — integrazione con sistemi di pagamento per gestire piani e limiti per tenant

Architettura: database condiviso vs separato

La multi-tenancy di Filament supporta entrambi gli approcci, ma con trade-off diversi.

Database condiviso con colonna tenant_id

Approccio più comune e semplice da gestire. Tutte le tabelle hanno una colonna team_id (o equivalente) e Filament applica un global scope su ogni query. Vantaggi: una sola istanza del database, migration centralizzate, backup semplificato. Svantaggi: se lo scope viene dimenticato in una query custom, i dati di un tenant possono fuoriuscire.

Database separato per tenant

Ogni tenant ha il proprio database. Isolamento totale dei dati, performance prevedibili per tenant e possibilità di backup e restore individuali. Svantaggi: complessità operativa maggiore, migration da eseguire su ogni database, query cross-tenant impossibili senza logica aggiuntiva. Questo approccio ha senso per SaaS enterprise dove l'isolamento dei dati è un requisito contrattuale.

Configurazione pratica: i passaggi chiave

Configurare la multi-tenancy in Filament 5 richiede pochi passaggi ben definiti:

• Creare il model tenant — una classe Eloquent come Team con i campi necessari (nome, slug, logo, impostazioni)
• Definire la relazione utente-tenant — tipicamente una BelongsToMany attraverso una tabella pivot con ruolo
• Configurare il panel — nel PanelProvider, chiamare ->tenant(Team::class) per attivare la multi-tenancy
• Aggiungere il trait ai model — ogni model che deve essere filtrato per tenant implementa il trait HasTenantScope
• Personalizzare la registrazione — opzionalmente, definire un form di registrazione tenant con i campi necessari per l'onboarding

Gestione dei permessi per tenant

Il plugin Shield di Filament si integra perfettamente con la multi-tenancy. Si definiscono ruoli e permessi a livello di tenant, così lo stesso utente può essere amministratore in un'organizzazione e avere accesso limitato in un'altra. Questo è fondamentale per consulenti, agenzie e professionisti che lavorano con più clienti contemporaneamente.

Quando serve la multi-tenancy

La multi-tenancy non è sempre necessaria e aggiunge complessità. Ha senso in questi scenari specifici:

• SaaS multi-azienda — la stessa applicazione venduta a più clienti, ognuno con i propri dati e utenti
• Gestionali multi-filiale — un'azienda con più sedi o divisioni che devono operare in modo indipendente
• Piattaforme white-label — applicazioni brandizzate diversamente per ogni cliente, con funzionalità e limiti configurabili
• Marketplace con vendor — ogni venditore gestisce il proprio catalogo, ordini e clienti in modo separato

Se il progetto serve una sola azienda con un solo set di dati, la multi-tenancy è overkill. In quel caso, un semplice sistema di ruoli e permessi copre le esigenze senza complessità aggiuntiva.

Sicurezza e testing nella multi-tenancy

Il rischio più grande in un sistema multi-tenant è il data leaking: un tenant che vede o modifica i dati di un altro. Per questo motivo, il testing diventa critico.

Filament facilita il testing della multi-tenancy con helper dedicati. Si può simulare l'accesso come utente di un tenant specifico e verificare che le query restituiscano solo i dati corretti. È buona pratica scrivere test che tentano esplicitamente di accedere a dati di un altro tenant e verificano che l'accesso venga negato.

A livello infrastrutturale, è consigliabile usare middleware dedicati che verificano il tenant attivo a ogni richiesta e monitorare i log per accessi anomali. La sicurezza della multi-tenancy non è un aspetto da dare per scontato: va verificata attivamente con test automatizzati e audit periodici.

La multi-tenancy come valore per il freelance

Come sviluppatore freelance, la multi-tenancy di Filament apre opportunità interessanti. Invece di sviluppare un applicativo custom per ogni cliente, si sviluppa una piattaforma multi-tenant e la si vende come servizio. Il costo di sviluppo si ammortizza su più clienti, la manutenzione è centralizzata e ogni nuovo tenant è un ricavo aggiuntivo con costo marginale vicino allo zero.

Filament 5 rende questo modello di business praticabile anche per un freelance o un piccolo team, perché la complessità della multi-tenancy viene gestita dal framework invece che dal codice custom.