Come integrare Supabase con Laravel per database e storage

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

Se lavori con Laravel e sei dedicato a programmazione backend e hai voglia di fare il salto verso un database PostgreSQL moderno e gestito come SupabaseProbabilmente avrai notato che non basta modificare un paio di variabili nel file .env. Ci sono dettagli di connessione, schemi, autenticazione e archiviazione dei file che, se trascurati, possono portare ad alcuni errori piuttosto criptici.

Inoltre, quando vuoi fare un ulteriore passo avanti e utilizzare Supabase come archivio di file Se integrato con il sistema di storage di Laravel, le cose diventano un po' più complesse: chiavi di servizio, bucket, endpoint, driver Flysystem personalizzati, ecc. La buona notizia è che tutto, database, storage e gestione UUID, può essere integrato perfettamente in modo abbastanza pulito.

Connessione di Laravel al database Supabase

Il primo passo è avere un progetto Laravel funzionante e collegarlo al database PostgreSQL fornito da Supabase. Per questo, è necessario un ambiente con PHP e Composer aggiornati e crea un nuovo progetto o usane uno esistente. Dalla console, genera semplicemente il progetto con il tipico comando Laravel e poi inizia a configurare la connessione.

Una volta definito lo scheletro del progetto, il passo usuale è installare un semplice sistema di autenticazione. Laravel Breeze si adatta molto bene perché include Modelli di lame e flusso di accesso e registrazione di baseCiò consente di verificare rapidamente che la connessione al database sia configurata correttamente e che sia possibile creare utenti senza problemi.

Per ottenere i dettagli della connessione, accedi al tuo pannello Supabase e crea un nuovo progetto di database (puoi farlo direttamente da database.nuovo(che reindirizza alla procedura guidata). Se non hai ancora un account, vedrai prima la schermata di registrazione; se ne hai già uno, andrai direttamente alle impostazioni del progetto e alla sezione in cui puoi controllare la stringa di connessione.

All'interno della pagina del progetto, nella sezione connessioni, troverai un pulsante come "Connect" o simile. Quando clicchi, Supabase ti mostra diversi formati di stringa di connessione (URI, parametri individuali, ecc.). Copia l'URI completo, ma ricorda che devi sostituire la password per quello effettivamente utilizzato nel database, poiché spesso ne viene visualizzato uno predefinito o un segnaposto.

Con queste informazioni, devi andare 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 è che tutto punti a Cluster Postgres 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.phpSebbene sia possibile utilizzare direttamente il driver pgsql fornito con il framework, quando si lavora con Supabase è comune applicare alcune modifiche aggiuntive, in particolare per quanto riguarda gli schemi e le opzioni specifiche di Postgres.

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

'pgsql' => ,

La chiave qui è nel parametro percorso_di_ricercaSupabase, di default, utilizza lo schema pubblico, ovvero quello esposto tramite le sue API. Se si desidera mantenere la propria applicazione Laravel separata da quello schema ed evitare conflitti di tabelle o policy, è altamente consigliato modificare search_path, ad esempio, con il proprio schema. laravel, come si vede nell'esempio precedente.

In questo modo, le migrazioni e le tabelle generate dal progetto verranno create in quello schema alternativo e non in pubblico. Questa separazione semplifica notevolmente la gestione. regole di sicurezza, RLS e accesso dal pannello Supabase senza calpestare nulla che non dovresti e mantenendo organizzata la struttura del database.

Una volta modificato il file di configurazione, è possibile avviare le migrazioni utilizzando i consueti comandi Laravel. Questo creerà le tabelle di autenticazione e tutte le altre tabelle definite. Se tutto è configurato correttamente, i comandi verranno eseguiti sul server. Supabase Postgres senza che tu debba fare altro.

Una volta completate le migrazioni, avvia il server di sviluppo con `artisan serve` e prova a registrare e ad accedere agli utenti. Se non si verificano errori di connessione o di migrazione, significa che Laravel funziona correttamente. comunicare correttamente con Supabase e tu puoi continua a costruire la tua logica aziendale normalmente.

Utilizzo di un driver Supabase specifico in Laravel

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

Questo pacchetto, distribuito come prahsys/laravel-supabase, viene installato tramite Composer e registra un driver aggiuntivo chiamato supabase che è possibile utilizzare nel file config/database.php. Internamente, è basato sul driver Postgres di Laravel, ma incorpora impostazioni e grammatiche di ricerca ottimizzato per l'ambiente specifico di Supabase.

Una volta installato, potresti dichiarare qualcosa di simile a quanto segue all'interno di sezione 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 relazioneIn questo modo si evita di dover scrivere manualmente il casting per ogni query complessa.

Il pacchetto è inoltre progettato per adattarsi bene alle versioni moderne del framework e di PHP, offrendo compatibilità ufficiale con Laravel 10.x, 11.x, 12.x e con PHP dalla versione 8.1 in poi, così come 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 una maggiore velocità, oppure preparare un file `.env.testing` che punti al proprio Supabase ed eseguire `composer test-supabase` per verificarne il comportamento in un ambiente reale. Postgres remoto.

Gestione UUID in Supabase e Laravel

Supabase ha una particolarità con le colonne UUID: se si tenta di confrontare un UUID direttamente con una stringa di testo senza eseguire il cast, la query potrebbe falliscono o restituiscono risultati inaspettatiIn un Postgres "semplice" è possibile risolvere questo problema con cast globali o operatori personalizzati, ma in Supabase queste personalizzazioni globali non sono consentite.

Questo implica che un'indagine diretta sullo stile:

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

Non funzionerà come ci si aspetterebbe. Tuttavia, se si esegue il casting esplicito:

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

La query ha avuto successo. Il problema è che in Laravel, quando si scrivono query con Eloquent o il query builder, non si vuole andare mettendo CAST in ogni doveÈ qui che entra in gioco il driver supabase del pacchetto sopra menzionato, che si occupa di aggiungere quei cast per te.

Con quel driver attivo, puoi eseguire domande frequenti come:

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

E non solo nelle consultazioni dirette, ma anche in si unisceAd esempio, se vuoi recuperare i post e unirli alla tabella degli utenti utilizzando un campo UUID, puoi fare qualcosa del genere:

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

Il conducente è responsabile dell'applicazione del calchi necessari per il testo nelle colonne UUID pertinenti, in modo trasparente. In questo modo, il codice rimane idiomatico per Laravel e non è necessario scrivere codice SQL grezzo o usare strani trucchi in ogni query complessa.

Se si desidera un controllo più preciso su quali colonne sono considerate UUID, il pacchetto offre la caratteristica CastsUuidColumns per i tuoi modelli Eloquent. Usalo semplicemente nella classe del modello e definisci 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 per impostazione predefinita e aggiunge qualsiasi colonna dichiarata nella proprietà. $uuidColumns e comunica tali informazioni al generatore di query in modo che sappia dove applicare i cast. Pertanto, tutti gli accessi ai dati che coinvolgono gli UUID diventano coerente e automatizzato.

Per casi ancora più avanzatiÈ possibile registrare un rilevatore di colonne UUID personalizzato. Utilizzando il pacchetto PostgresGrammar, è possibile specificare una funzione di callback che, in base al nome della colonna o al contesto della query, decida se trattarla come 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 impostata, il sistema può considerare come UUID tutte le colonne il cui nome ha un certo schema o è all'interno di un elenco specifico, adattandosi a convenzioni di denominazione molto 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 puoi sfruttare come Disco Laravel utilizzando FlysystemA questo scopo, esiste un adattatore specifico che consente di trattare Supabase Storage come un semplice driver all'interno di config/filesystems.php.

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

Nel file config/filesystems.phpAll'interno dei dischi array, dovresti aggiungere qualcosa di simile a quanto segue:

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

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

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

L'URL generale del disco viene normalmente lasciato nullo in modo che l'adattatore lo derivi automaticamente dall'endpoint. È consigliabile modificarlo solo se si utilizza un proxy o CDN intermedio e si desidera che i percorsi generati puntino a quel dominio anziché al dominio Supabase nativo.

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

Un problema abbastanza comune quando si tenta di caricare file su Supabase Storage da Laravel è la ricezione di messaggi come “Impossibile scrivere il file nella posizione: uploads/…”Di solito questo indica che, nonostante il driver sia configurato, Supabase nega l'operazione di scrittura a causa di autorizzazioni insufficienti o di una chiave configurata in modo errato.

Nel disco di base di config/filesystems.php, la configurazione menziona l'utilizzo una "chiave privilegiata" nel campo chiave, indicando esplicitamente che una chiave di sola lettura non funzionerà. Ciò significa che è necessario utilizzare una chiave di servizio con autorizzazioni di scrittura sul bucket, non semplicemente una chiave API pubblica destinata al client o una chiave destinata alla compatibilità S3 senza autorizzazioni di modifica.

Nel pannello Supabase, all'interno della sezione di configurazione API e storage, troverai sia le chiavi anonime che le service_role o equivalenteQuesti sono quelli con privilegi estesi. È quella chiave di servizio, e non quella pubblica, che dovresti inserire nella variabile SUPABASE_SECRET_ACCESS_KEY, che il driver leggerà tramite env('SUPABASE_SECRET_ACCESS_KEY').

Se hai eseguito test con la chiave S3 dalla configurazione di archiviazione o con le chiavi API generiche dal progetto, è molto probabile che tali credenziali non abbiano l'autorizzazione per scrivere sul bucket specifico, con conseguente errore di scrittura. Modificando il valore della chiave in chiave di servizio valida con permessi di scrittura E confermando che il bucket esiste e che è scritto correttamente, il problema è solitamente risolto.

Oltre alla chiave, è importante verificare che il bucket definito in SUPABASE_STORAGE_BUCKET corrisponda esattamente a quello creato nell'interfaccia Supabase, rispettando sia le maiuscole che le 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 il funzionamento dell'adattatore. individuare la destinazione effettiva dei file.

Flusso di lavoro con Laravel Breeze, Blade e Supabase Storage

Una volta configurato il database e l'archiviazione, il passo successivo è integrare tutto con il tuo Interfaccia Laravel Breeze e modelli BladeIn questo modo, gli utenti possono registrarsi, autenticarsi e caricare file su Supabase senza uscire dall'ecosistema Laravel.

All'interno dei tuoi controller, useresti il Facciata di stoccaggio puntando al disco supabase. Ad esempio, per caricare un file ricevuto da un modulo con un input file, potresti fare qualcosa del genere:

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

Questo codice dice a Laravel di usare il disco supbase e posiziona il file nella cartella di caricamento virtuale all'interno del bucket configurato. Se la chiave e l'endpoint sono corretti, il file verrà caricato nello storage Supabase e sarà possibile recuperarne il percorso o generare URL pubblici o firmati utilizzando 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 è ridotto a regola config/filesystems.php e le variabili di ambiente, senza toccare la logica aziendale.

Combinando questo con Blade e Breeze, puoi offrire moduli di caricamento, elenchi di file e link per il download completamente integrati nell'esperienza utente della tua applicazione. Inoltre, l'approccio basato su bucket e policy di Supabase Storage ti consente di sfruttare al meglio le sue controlli di accesso e regole di sicurezza per definire cosa ogni utente può vedere o scaricare.

L'intero ecosistema di pacchetti, driver e configurazioni consente a Laravel di lavorare molto comodamente con Supabase, sia per quanto riguarda i dati relazionali con Postgres che per... archiviazione dei file e gestione degli UUIDRegolando correttamente le chiavi, gli schemi e i driver, si ottiene un'integrazione molto solida che evita molti degli errori tipici che si verificano quando si cerca di connettere entrambe le piattaforme manualmente e senza questi livelli di assistenza.

Collegando Laravel con Supabase per database e storage, sfruttando il driver Supabase dedicato per gestire gli UUID senza problemi e utilizzando l'adattatore Flysystem per lo storage, è possibile creare applicazioni moderne in cui L'intera infrastruttura complessa è incapsulata Dietro le quinte dell'API pulita di Laravel, dalle migrazioni e autenticazione al caricamento dei file in bucket protetti.