Come integrare Supabase con Laravel per database e storage

Informatec Digital » Risorse » Come integrare Supabase con Laravel per database e archiviazione

Se lavori con Laravel e ti dedichi alla programmazione backend , e stai pensando di passare a un database PostgreSQL gestito e moderno come Supabase , probabilmente ti sarai reso conto che modificare semplicemente un paio di variabili nel file .env non è sufficiente. Ci sono dettagli di connessione, schemi, autenticazione e archiviazione dei file che, se trascurati, possono portare a errori piuttosto criptici.

Inoltre, quando si desidera fare un ulteriore passo avanti e utilizzare Supabase come archivio file integrato con il sistema di archiviazione di Laravel (Storage), le cose si complicano un po': chiavi di servizio, bucket, endpoint, driver Flysystem personalizzati, ecc. La buona notizia è che tutto può essere perfettamente integrato – database, archiviazione e gestione degli UUID – in modo piuttosto pulito.

Connessione di Laravel al database Supabase

Il primo passo consiste nell'avere un progetto Laravel funzionante e collegarlo al database Postgres fornito da Supabase. Per fare ciò, è necessario un ambiente con PHP e Composer aggiornati , e si può creare un nuovo progetto o utilizzarne uno esistente. Dalla console, è sufficiente generare il progetto utilizzando il comando standard di Laravel e quindi iniziare a configurare la connessione.

Una volta definita la struttura del progetto, la prassi comune è quella di installare un semplice sistema di autenticazione. Laravel Breeze si integra perfettamente in questo contesto, poiché include template Blade e un flusso di login e registrazione di base , che consente di verificare rapidamente che la connessione al database sia configurata correttamente e che sia possibile creare utenti senza problemi.

Per ottenere i dettagli di connessione, accedi alla dashboard di Supabase e crea un nuovo progetto di database (puoi farlo direttamente da `database.new` , che ti reindirizza alla procedura guidata). Se non hai ancora un account, visualizzerai prima la schermata di registrazione; se ne hai già uno, verrai indirizzato direttamente alle impostazioni del progetto e alla sezione in cui puoi trovare la stringa di connessione.

Nella pagina del progetto, nella sezione relativa alla connessione, troverai un pulsante "Connetti" o qualcosa di simile. Cliccandoci sopra, verranno visualizzati diversi formati di stringa di connessione (URI, singoli parametri, ecc.). Copia l'URI completo, ma ricorda di sostituire la password con quella che utilizzi effettivamente per il database, poiché spesso viene visualizzata una password predefinita o un segnaposto.

Con queste informazioni, devi accedere al file .env del tuo progetto Laravel e aggiornare le variabili DB_HOST, DB_PORT, DB_DATABASE, DB_USERNAME e DB_PASSWORD, oppure configurare la variabile DATABASE_URL se preferisci utilizzare il formato stringa completo. L'obiettivo è garantire che tutto punti al cluster Postgres di Supabase e non al tuo localhost.

Configurare il driver Postgres e lo schema Supabase in Laravel

In Laravel, il file chiave per la configurazione del database è config/database.php . Sebbene sia possibile utilizzare direttamente il driver pgsql fornito con il framework, quando si lavora con Supabase è comune applicare alcune impostazioni aggiuntive, soprattutto per quanto riguarda gli schemi e le opzioni specifiche di PostgreSQL.

Una tipica configurazione di Postgres in Laravel potrebbe apparire così, all'interno dell'array connections, sotto la chiave 'pgsql' :

'pgsql' => ,

Il punto cruciale sta nel parametro `search_path` . Supabase, per impostazione predefinita, utilizza lo schema `public`, ovvero quello esposto tramite le sue API. Se si desidera mantenere l'applicazione Laravel separata da tale schema ed evitare conflitti di tabelle o policy, è fortemente consigliato modificare il parametro `search_path` con il proprio schema, ad esempio `laravel` , come mostrato nell'esempio precedente.

In questo modo, le migrazioni e le tabelle generate dal progetto verranno create in questo schema alternativo e non in quello pubblico. Questa separazione semplifica notevolmente la gestione delle regole di sicurezza, degli RLS e degli accessi dal pannello di controllo di Supabase, evitando di sovrascrivere elementi non necessari e mantenendo la struttura del database organizzata.

Una volta modificato il file di configurazione, è possibile eseguire le migrazioni utilizzando i comandi standard di Laravel. Questo creerà le tabelle di autenticazione e tutte le altre tabelle definite. Se tutto è configurato correttamente, i comandi verranno eseguiti automaticamente sul server PostgreSQL di Supabase.

Una volta completate le migrazioni, avvia il server di sviluppo con `artisan serve` e prova a registrare e ad accedere con gli utenti. Se non compaiono errori di connessione o di migrazione, significa che Laravel comunica correttamente con Supabase e puoi continuare a sviluppare la logica di business come di consueto.

Utilizzo di un driver Supabase specifico in Laravel

Sebbene il driver standard pgsql funzioni, esiste un pacchetto che aggiunge un driver di database supabase per Laravel , estendendo il comportamento di PostgreSQL con miglioramenti molto utili, soprattutto per quanto riguarda la gestione delle colonne UUID e il modo in cui vengono costruite le query.

Questo pacchetto, distribuito come prahsys/laravel-supabase, si installa tramite Composer e registra un driver aggiuntivo chiamato supabase che è possibile utilizzare nel file config/database.php. Internamente, si basa sul driver Postgres di Laravel, ma incorpora impostazioni e grammatiche di query ottimizzate per lo specifico ambiente Supabase.

Una volta installato, potresti dichiarare qualcosa di simile a quanto segue nella sezione delle connessioni :

'connections' => ,
    // otras conexiones...
],

Il vantaggio di utilizzare questo driver è che si ottiene comunque tutta la potenza del motore Postgres, ma gestisce anche automaticamente alcuni dettagli delicati di Supabase, soprattutto quando si lavora con UUID come chiavi primarie o campi di relazione . Questo evita di dover scrivere manualmente i casting in ogni query complessa.

Il pacchetto è inoltre progettato per integrarsi perfettamente con le versioni moderne del framework e di PHP, offrendo compatibilità ufficiale con Laravel 10.x, 11.x e 12.x e con PHP dalla versione 8.1 in poi, nonché con qualsiasi database PostgreSQL standard, incluso ovviamente Supabase.

Per garantire che tutto funzioni correttamente, il pacchetto include una suite di test automatizzati. È possibile eseguire i test con il comando `composer test`, che utilizzerà un database SQLite in memoria per velocizzare le operazioni, oppure preparare un file `.env.testing` che punti al proprio Supabase ed eseguire `composer test-supabase` per verificare il comportamento in un ambiente reale con Postgres remoto.

Gestione UUID in Supabase e Laravel

Supabase presenta una particolarità con le colonne UUID: se si tenta di confrontare direttamente un UUID con una stringa di testo senza effettuare il casting, la query potrebbe fallire o restituire risultati inattesi . In un ambiente PostgreSQL puro, questo problema potrebbe essere risolto con casting globali o operatori personalizzati, ma Supabase non consente tali personalizzazioni globali.

Ciò implica che una query diretta dello stile:

SELECT *
FROM users
WHERE id = '123e4567-e89b-12d3-a456-426614174000';

Non funzionerà come ti aspetteresti. Tuttavia, se esegui il casting esplicito:

SELECT *
FROM users
WHERE CAST(id AS TEXT) = '123e4567-e89b-12d3-a456-426614174000';

La query è andata a buon fine. Il problema è che in Laravel, quando si scrivono query con Eloquent o con il query builder, non si desidera aggiungere CAST a ogni clausola WHERE . È qui che entra in gioco il driver supabase del pacchetto menzionato in precedenza, che aggiunge automaticamente questi CAST.

Con quel driver attivo, è possibile eseguire query comuni come:

$user = User::find($uuidString);
$user = User::where('id', $uuidString)->first();
$users = User::whereIn('id', )->get();

E non solo nelle query dirette, ma anche nelle join . Ad esempio, se si desidera recuperare i post e unirli alla tabella degli utenti utilizzando un campo UUID, si potrebbe fare qualcosa del genere:

$posts = Post::join('users', 'posts.user_id', '=', 'users.id')
    ->where('users.email', '[email protected]')
    ->get();

Il driver gestisce in modo trasparente l'applicazione dei cast di testo necessari alle colonne UUID pertinenti. In questo modo, il codice rimane conforme agli standard di Laravel e non è necessario scrivere codice SQL grezzo o utilizzare strani trucchi in ogni query complessa.

Se desideri un controllo più preciso su quali colonne vengono considerate UUID, il pacchetto offre il trait CastsUuidColumns per i tuoi modelli Eloquent. È sufficiente utilizzarlo nella classe del modello e definire un array protetto di colonne aggiuntive:

use Prahsys\Supabase\Traits\CastsUuidColumns;

class Post extends Model
{
    use CastsUuidColumns;

    protected $uuidColumns = ;
}

Questa caratteristica svolge tre funzioni importanti: include la chiave primaria come UUID predefinito, aggiunge tutte le colonne dichiarate alla proprietà `$uuidColumns` e comunica queste informazioni al query builder in modo che sappia dove applicare i cast. Ciò rende coerente e automatizzato tutto l'accesso ai dati che coinvolge gli UUID.

Per casi ancora più avanzati , è possibile registrare un rilevatore di colonne UUID personalizzato. Utilizzando PostgresGrammar del pacchetto, è possibile specificare una funzione di callback che, in base al nome della colonna o al contesto della query, decide se deve essere trattata come un UUID. Ad esempio:

use Prahsys\Supabase\Database\Query\Grammars\PostgresGrammar;

PostgresGrammar::detectUuidColumnsWith(function ($columnName, $query) {
    return str_contains($columnName, 'uuid_')
        || in_array($columnName, );
});

Con questa funzione configurata, il sistema può considerare come UUID tutte le colonne il cui nome segue un determinato schema o è presente in un elenco specifico, adattandosi alle convenzioni di denominazione specifiche del tuo progetto.

Integrare Supabase Storage come file system in Laravel

Oltre al database, molti progetti necessitano di archiviare immagini, documenti o altri file caricati dagli utenti. Supabase include un servizio di archiviazione basato su bucket che può essere utilizzato come disco di Laravel tramite Flysystem . È disponibile un adattatore specifico per trattare Supabase Storage come un driver aggiuntivo all'interno del file config/filesystems.php.

Il pacchetto in questione fornisce un adattatore Flysystem che si integra perfettamente con il sistema di archiviazione del framework. Soddisfa i requisiti minimi di PHP >= 8.1, Laravel 10.x e 11.x e l'estensione PHP fileinfo (ext-fileinfo), che Laravel raccomanda in genere per la gestione dei file. L'installazione avviene tramite Composer e, una volta incluso, è sufficiente definire il disco supabase nella configurazione.

Nel file config/filesystems.php , all'interno dell'array disks, dovresti aggiungere qualcosa di simile al seguente:

'supabase' => ,
    ],
    'signedUrlExpires' => 60 * 60 * 24,
],

Il parametro `bucket` è solitamente semplicemente il nome del bucket di archiviazione creato nella dashboard di Supabase (ad esempio, `myapp-file-uploads`). L'`endpoint` è l'URL di base del servizio di archiviazione del progetto, visibile anche nella sezione corrispondente della dashboard, e viene solitamente derivato dall'URL del progetto e dalla regione.

L'opzione `public` indica se il contenuto del bucket verrà considerato pubblico per impostazione predefinita. Se `true`, l'adattatore genererà URL accessibili senza firma speciale; se `false`, entra in gioco l'opzione `defaultUrlGeneration`, che può forzare la generazione di URL firmati con un tempo di scadenza specificato da `signedUrlExpires`. Questa configurazione consente di bilanciare sicurezza e praticità a seconda del tipo di file gestiti.

L'URL generale del disco viene normalmente lasciato nullo in modo che l'adattatore lo derivi automaticamente dall'endpoint. È necessario modificarlo solo se si utilizza un proxy intermedio o una CDN e si desidera che le route generate puntino a tale dominio anziché al dominio nativo di Supabase.

Risolvi gli errori di caricamento e scopri la chiave di Supabase Storage

Un problema piuttosto comune quando si tenta di caricare file su Supabase Storage da Laravel è la ricezione di messaggi come "Impossibile scrivere il file nella posizione: uploads/..." . Questo di solito indica che, sebbene il driver sia configurato, Supabase nega l'operazione di scrittura a causa di permessi insufficienti o di una configurazione della chiave errata.

Nel file di configurazione del disco supabase, `config/filesystems.php`, la configurazione specifica l'utilizzo di una "chiave privilegiata" nel campo `key`, indicando esplicitamente che una chiave di sola lettura non funzionerà. Ciò significa che è necessario utilizzare una chiave di servizio con permessi di scrittura sul bucket, e non semplicemente una chiave API pubblica lato client o una chiave di compatibilità S3 senza permessi di modifica.

Nel pannello di controllo di Supabase, nella sezione di configurazione API e storage, troverai sia chiavi anonime che chiavi service_role (o equivalenti) , che dispongono di privilegi estesi. È questa chiave di servizio, e non quella pubblica, che devi inserire nella variabile SUPABASE_SECRET_ACCESS_KEY, che il driver leggerà poi utilizzando env('SUPABASE_SECRET_ACCESS_KEY').

Se hai effettuato i test con la chiave S3 della configurazione di archiviazione o con le chiavi API generiche del progetto, è molto probabile che tali credenziali non dispongano dei permessi di scrittura per il bucket specifico, causando l'errore di scrittura. Solitamente, la modifica del valore della chiave con una chiave di servizio valida con permessi di scrittura e la verifica dell'esistenza e del nome corretto del bucket risolvono il problema.

Oltre alla password, è importante verificare che il bucket definito in SUPABASE_STORAGE_BUCKET corrisponda esattamente a quello creato nell'interfaccia Supabase, rispettando maiuscole e minuscole, e che l'endpoint corrisponda all'URL corretto per quell'istanza di storage. Un dettaglio come un carattere in più o un dominio errato può impedire all'adattatore di individuare la destinazione effettiva dei file.

Flusso di lavoro con Laravel Breeze, Blade e Supabase Storage

Una volta configurati il ​​database e lo storage, il passo successivo logico è integrare tutto con l' interfaccia Laravel Breeze e i template Blade . In questo modo, gli utenti possono registrarsi, autenticarsi e caricare file su Supabase senza uscire dall'ecosistema Laravel.

All'interno dei controller, si utilizzerebbe la facciata Storage che punta al disco supabase. Ad esempio, per caricare un file ricevuto da un modulo con un campo di input per i file, si potrebbe procedere in questo modo:

if ($request->hasFile('file')) {
    $path = $request->file('file')
        ->store('uploads', 'supabase');
}

Questo codice indica a Laravel di utilizzare il disco Supabase e di posizionare il file all'interno della cartella virtuale "uploads" nel bucket configurato. Se la chiave e l'endpoint sono corretti, il file verrà caricato nello storage di Supabase e sarà possibile recuperarne il percorso o generare URL pubblici o firmati utilizzando i metodi di storage standard.

Il vantaggio di questo approccio è che l'applicazione mantiene un'unica interfaccia per l'archiviazione, indipendentemente dal fatto che utilizzi un disco locale, Amazon S3, Supabase o un altro servizio supportato. Il cambio di provider si riduce alla modifica del file config/filesystems.php e delle variabili d'ambiente, senza influire sulla logica di business.

Combinando questa soluzione con Blade e Breeze, è possibile offrire moduli di caricamento, elenchi di file e link per il download completamente integrati nell'esperienza utente dell'applicazione. Inoltre, l'approccio di Supabase Storage basato su bucket e policy consente di sfruttare i controlli di accesso e le regole di sicurezza per definire cosa ogni utente può visualizzare o scaricare.

Questo intero ecosistema di pacchetti, driver e configurazioni permette a Laravel di integrarsi perfettamente con Supabase, sia per quanto riguarda i dati relazionali con PostgreSQL, sia per l'archiviazione dei file e la gestione degli UUID . Configurando correttamente chiavi, schemi e driver, si ottiene un'integrazione molto solida che evita molti degli errori tipici che si verificano quando si tenta di connettere manualmente le due piattaforme senza questi livelli di supporto.

Integrando Laravel con Supabase per database e storage, sfruttando il driver dedicato di Supabase per gestire gli UUID senza problemi e utilizzando l'adattatore Flysystem per lo storage, è possibile creare applicazioni moderne in cui tutta la complessa infrastruttura è incapsulata dietro l'API pulita di Laravel, dalle migrazioni e l'autenticazione al caricamento dei file in bucket sicuri.