Hur man integrerar Supabase med Laravel för databas och lagring

Informatec Digital » Resurser » Hur man integrerar Supabase med Laravel för databaser och lagring

Om du arbetar med Laravel och är dedikerad till backend-programmering , och du vill ta steget till en modern, hanterad PostgreSQL- databas som Supabase , har du förmodligen insett att det inte räcker med att bara ändra ett par variabler i .env-filen. Det finns anslutningsdetaljer, scheman, autentisering och fillagring som, om de försummas, kan leda till en del ganska kryptiska fel.

Dessutom, när man vill gå ett steg längre och använda Supabase som fillagring integrerad med Laravels disksystem (Storage), blir det lite mer komplicerat: servicenycklar, buckets, endpoints, anpassade Flysystem-drivrutiner, etc. Den goda nyheten är att allt kan integreras perfekt – databasen, lagringen och UUID-hanteringen – på ett ganska rent sätt.

Ansluta Laravel till Supabase-databasen

Det första steget är att ha ett fungerande Laravel-projekt och länka det till Postgres-databasen som tillhandahålls av Supabase. För detta behöver du en miljö med uppdaterad PHP och Composer , och du kan skapa ett nytt projekt eller använda ett befintligt. Från konsolen genererar du helt enkelt projektet med standard Laravel-kommandot och börjar sedan konfigurera anslutningen.

När du väl har projektets ramverk på plats är det vanligt att installera ett enkelt autentiseringssystem. Laravel Breeze passar mycket bra in eftersom det inkluderar Blade-mallar och ett grundläggande inloggnings- och registreringsflöde , vilket gör att du snabbt kan validera att din databasanslutning är korrekt konfigurerad och att du kan skapa användare utan problem.

För att hämta anslutningsinformationen, logga in på din Supabase-instrumentpanel och skapa ett nytt databasprojekt (du kan göra detta direkt från `database.new` , som omdirigerar till guiden). Om du inte har ett konto ännu ser du först registreringsskärmen; om du redan har ett går du direkt till projektinställningarna och avsnittet där du hittar anslutningssträngen.

På projektsidan, i anslutningsavsnittet, hittar du en knapp som heter "Anslut" eller något liknande. Om du klickar på den visas flera format för anslutningssträngar (URI, individuella parametrar etc.). Kopiera hela URI:n, men kom ihåg att ersätta lösenordet med det du faktiskt använder för databasen, eftersom ett standardlösenord eller en platshållare ofta visas.

Med den informationen behöver du gå till ditt Laravel-projekts .env-fil och uppdatera variablerna DB_HOST, DB_PORT, DB_DATABASE, DB_USERNAME och DB_PASSWORD, eller konfigurera variabeln DATABASE_URL om du föredrar att använda full strängformat. Målet är att säkerställa att allt pekar på Supabase Postgres-klustret och inte på din localhost.

Konfigurera Postgres-drivrutinen och Supabase-schemat i Laravel

I Laravel är nyckelfilen för databaskonfiguration config/database.php . Även om du kan använda pgsql-drivrutinen som följer med ramverket direkt, är det vanligt att man tillämpar ytterligare inställningar när man arbetar med Supabase, särskilt gällande scheman och Postgres-specifika alternativ.

En typisk Postgres-konfiguration i Laravel kan se ut så här, inom connections-arrayen, under nyckeln 'pgsql' :

'pgsql' => ,

Nyckeln här ligger i parametern `search_path` . Supabase använder som standard schemat `public`, vilket är det som exponeras via dess API:er. Om du vill hålla din Laravel-applikation separat från det schemat och undvika tabell- eller policykonflikter rekommenderas det starkt att ändra `search_path` till ditt eget schema, till exempel `laravel` , som ses i föregående exempel.

På så sätt skapas migreringar och tabeller som genereras av ditt projekt i detta alternativa schema och inte offentligt. Denna separation förenklar avsevärt hanteringen av säkerhetsregler, RLS och åtkomst från Supabase-panelen utan att skriva över något du inte borde, samtidigt som databasstrukturen hålls organiserad.

När du har justerat konfigurationsfilen kan du köra migreringarna med standard Laravel-kommandon. Detta skapar autentiseringstabellerna och alla andra tabeller du har definierat. Om allt är korrekt konfigurerat kommer kommandona att köras automatiskt mot Supabase Postgres-servern .

När migreringarna är klara, starta utvecklingsservern med `artisan serve` och försök registrera och logga in användare. Om inga anslutnings- eller migreringsfel visas betyder det att Laravel kommunicerar korrekt med Supabase och du kan fortsätta bygga din affärslogik som vanligt.

Använda en specifik Supabase-drivrutin i Laravel

Även om standarddrivrutinen för pgsql fungerar, finns det ett paket som lägger till en supabase-databasdrivrutin för Laravel , vilket utökar PostgreSQLs beteende med mycket användbara förbättringar, särskilt vad gäller hanteringen av UUID-kolumner och hur frågor konstrueras.

Detta paket, distribuerat som prahsys/laravel-supabase, installeras via Composer och registrerar en ytterligare drivrutin som heter supabase som du kan använda i din config/database.php-fil. Internt är det baserat på Laravels Postgres-drivrutin, men innehåller inställningar och frågegrammatiker optimerade för den specifika Supabase-miljön.

När det är installerat kan du deklarera något liknande följande i anslutningsavsnittet :

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

Fördelen med att använda den här drivrutinen är att du fortfarande får tillgång till Postgres-motorns fulla kraft, men den hanterar också automatiskt vissa känsliga Supabase-detaljer, särskilt när man arbetar med UUID:er som primärnycklar eller relationsfält . Detta undviker att behöva skriva casting manuellt i varje komplex fråga.

Paketet är också utformat för att passa bra med moderna versioner av ramverket och PHP, och erbjuder officiell kompatibilitet med Laravel 10.x, 11.x och 12.x och med PHP från version 8.1 och framåt, såväl som alla vanliga PostgreSQL-databaser, inklusive naturligtvis Supabase.

För att säkerställa att allt fungerar korrekt innehåller paketet en uppsättning automatiserade tester. Du kan köra testerna med kommandot `composer test`, som använder en SQLite-databas i minnet för snabbare testning, eller förbereda en `.env.testing`-fil som pekar på din Supabase och köra `composer test-supabase` för att verifiera beteendet i en verklig miljö med fjärrstyrd Postgres.

UUID-hantering i Supabase och Laravel

Supabase har en egenhet med UUID-kolumner: om du försöker jämföra en UUID direkt med en textsträng utan att casta, kan frågan misslyckas eller returnera oväntade resultat . I en ren Postgres-miljö skulle du kunna lösa detta med globala castar eller anpassade operatorer, men Supabase tillåter inte sådana globala anpassningar.

Detta innebär att en direkt fråga av stilen:

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

Det kommer inte att fungera som du kanske förväntar dig. Men om du gör den explicita castingen:

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

Frågan lyckades. Problemet är att i Laravel, när du skriver frågor med Eloquent eller frågebyggaren, vill du inte lägga till CAST:er till varje WHERE-klausul . Det är där supabase-drivrutinen från det tidigare nämnda paketet kommer in, som lägger till dessa casts åt dig.

Med den drivrutinen aktiv kan du utföra vanliga frågor som:

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

Och inte bara i direkta frågor, utan även i joins . Om du till exempel vill hämta inlägg och koppla dem till tabellen users med hjälp av ett UUID-fält kan du göra något liknande:

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

Drivrutinen hanterar transparent tillämpningen av nödvändiga textomvandlingar på relevanta UUID-kolumner. På så sätt förblir din kod idiomatisk för Laravel, och du behöver inte skriva rå SQL eller använda konstiga knep i varje komplex fråga.

Om du vill ha bättre kontroll över vilka kolumner som betraktas som UUID, erbjuder paketet egenskapen CastsUuidColumns för dina Eloquent-modeller. Använd den helt enkelt i din modellklass och definiera en skyddad array av ytterligare kolumner:

use Prahsys\Supabase\Traits\CastsUuidColumns;

class Post extends Model
{
    use CastsUuidColumns;

    protected $uuidColumns = ;
}

Den här egenskapen gör tre viktiga saker: den inkluderar primärnyckeln som standard-UUID, lägger till alla kolumner du deklarerar till egenskapen `$uuidColumns` och kommunicerar denna information till frågebyggaren så att den vet var konverteringarna ska tillämpas. Detta gör all dataåtkomst som involverar UUID:er konsekvent och automatiserad.

För ännu mer avancerade fall kan du registrera en anpassad UUID-kolumndetektor. Med hjälp av PostgresGrammar från paketet kan du ange en callback-funktion som, baserat på kolumnnamnet eller frågekontexten, avgör om den ska behandlas som en UUID. Till exempel:

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

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

Med den här funktionen konfigurerad kan systemet betrakta alla kolumner vars namn har ett visst mönster eller finns inom en specifik lista som UUID, och anpassa sig till mycket specifika namngivningskonventioner för ditt projekt.

Integrera Supabase Storage som ett filsystem i Laravel

Förutom databasen behöver många projekt lagra bilder, dokument eller andra filer som laddats upp av användare. Supabase inkluderar en bucket-baserad lagringstjänst som du kan använda som Laravels disk via Flysystem . En specifik adapter finns tillgänglig för att behandla Supabase Storage som en extra drivrutin i config/filesystems.php.

Paketet i fråga tillhandahåller en Flysystem-adapter som integreras sömlöst med ramverkets lagringssystem. Den uppfyller minimikraven för PHP >= 8.1, Laravel 10.x och 11.x , och PHP fileinfo-ändelsen (ext-fileinfo), som Laravel vanligtvis rekommenderar för filhantering. Installationen görs med Composer, och när den väl är inkluderad behöver du bara definiera supabase-disken i konfigurationen.

I filen config/filesystems.php , i disks-arrayen, skulle du lägga till något liknande följande:

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

Parametern `bucket` är vanligtvis helt enkelt namnet på den lagringsbucket du skapade i Supabase-instrumentpanelen (till exempel `myapp-file-uploads`). `Endpoint` är bas-URL:en för projektets lagringstjänst, som också syns i motsvarande avsnitt av instrumentpanelen, och härleds vanligtvis från projektets URL och region.

Alternativet `public` anger om innehållet i hinken ska behandlas som offentligt som standard. Om `true` genererar adaptern tillgängliga URL:er utan en speciell signatur; om `false` aktiveras alternativet `defaultUrlGeneration`, vilket kan tvinga fram generering av signerade URL:er med en utgångstid som anges av `signedUrlExpires`. Den här konfigurationen låter dig balansera säkerhet och bekvämlighet beroende på vilken typ av filer du hanterar.

Den allmänna disk-URL:en lämnas normalt kvar som null så att adaptern automatiskt härleder den från slutpunkten. Du bör bara ändra den om du använder en mellanliggande proxy eller ett CDN och vill att de genererade vägarna ska peka på den domänen istället för den ursprungliga Supabase-domänen.

Felsök uppladdningsfel och förstå nyckeln till Supabase Storage

Ett ganska vanligt problem när man försöker ladda upp filer till Supabase Storage från Laravel är att man får meddelanden som "Det gick inte att skriva filen på platsen: uploads/…" . Detta indikerar vanligtvis att, trots att drivrutinen är konfigurerad, nekar Supabase skrivåtgärden på grund av otillräckliga behörigheter eller en felaktig nyckelkonfiguration.

I supabase-diskkonfigurationsfilen, `config/filesystems.php`, specificerar konfigurationen att man använder en "privilegierad nyckel" i fältet `key`, vilket uttryckligen anger att en skrivskyddad nyckel inte fungerar. Det betyder att du måste använda en servicenyckel med skrivbehörighet till bucketen, inte bara en offentlig API-nyckel på klientsidan eller en S3-kompatibilitetsnyckel utan modifieringsbehörigheter.

I Supabase-panelen, i avsnittet API- och lagringskonfiguration, hittar du både anonyma nycklar och service_role-nycklar (eller deras motsvarigheter) , vilka har utökade behörigheter. Det är denna servicenyckel, inte den publika, som du ska placera i variabeln SUPABASE_SECRET_ACCESS_KEY, som drivrutinen sedan läser med hjälp av env('SUPABASE_SECRET_ACCESS_KEY').

Om du har testat med S3-nyckeln från lagringskonfigurationen eller med projektets generiska API-nycklar är det mycket troligt att dessa autentiseringsuppgifter inte har skrivbehörighet till den specifika bucketen, vilket resulterar i skrivfelet. Att ändra nyckelvärdet till en giltig servicenyckel med skrivbehörighet och bekräfta att bucketen finns och har rätt namn löser vanligtvis problemet.

Förutom lösenordet är det viktigt att verifiera att hinken som definierats i SUPABASE_STORAGE_BUCKET exakt matchar den som skapats i Supabase-gränssnittet, med respekt för både stora och små bokstäver, och att slutpunkten motsvarar rätt URL för den lagringsinstansen. En detalj som ett extra tecken eller en felaktig domän kan förhindra att adaptern hittar filernas faktiska destination.

Arbetsflöde med Laravel Breeze, Blade och Supabase Storage

När du har konfigurerat din databas och lagring är nästa logiska steg att integrera allt med ditt Laravel Breeze-gränssnitt och Blade-mallar . På så sätt kan användare registrera, autentisera och ladda upp filer till Supabase utan att lämna Laravel-ekosystemet.

Inom dina kontroller skulle du använda Storage-fasaden som pekar mot Supabase-disken. För att till exempel ladda upp en fil som mottagits från ett formulär med en filinmatning kan du göra något liknande:

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

Denna kod instruerar Laravel att använda Supabase- disken och placera filen i den virtuella uppladdningsmappen i den konfigurerade bucketen. Om nyckeln och slutpunkten är korrekta kommer filen att laddas upp till Supabase-lagringen, och du kan hämta dess sökväg eller generera offentliga eller signerade URL:er med standardlagringsmetoder.

Fördelen med den här metoden är att din applikation har ett enda gränssnitt för lagring, oavsett om den använder en lokal disk, Amazon S3, Supabase eller någon annan tjänst som stöds. Att byta leverantör reduceras till att justera config/filesystems.php och miljövariabler, utan att påverka affärslogiken.

Genom att kombinera detta med Blade och Breeze kan du erbjuda uppladdningsformulär, fillistor och nedladdningslänkar helt integrerade i din applikations användarupplevelse. Dessutom låter Supabase Storages bucket- och policybaserade tillvägagångssätt dig utnyttja dess åtkomstkontroller och säkerhetsregler för att definiera vad varje användare kan visa eller ladda ner.

Hela detta ekosystem av paket, drivrutiner och konfigurationer gör att Laravel kan arbeta sömlöst med Supabase, både vad gäller relationsdata med Postgres och fillagring och UUID-hantering . Genom att korrekt konfigurera nycklar, scheman och drivrutiner uppnår du en mycket robust integration som undviker många av de typiska fel som uppstår när man försöker ansluta båda plattformarna manuellt utan dessa stödjande lager.

Genom att koppla Laravel till Supabase för databas och lagring, utnyttja den dedikerade Supabase-drivrutinen för att hantera UUID utan problem, och använda Flysystem-adaptern för lagring, kan du bygga moderna applikationer där all komplex infrastruktur är inkapslad bakom Laravels rena API, från migreringar och autentisering till att ladda upp filer till säkra buckets.