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

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

Om du arbetar med Laravel och är engagerad i backend-programmering och du känner för att ta steget till en databas modern, hanterad PostgreSQL som SupabaseDu har säkert märkt att det inte räcker 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 du vill gå ett steg längre och använda Supabase som fillagring När det integreras med Laravels lagringssystem blir det lite mer komplext: servicenycklar, buckets, endpoints, anpassade Flysystem-drivrutiner, etc. Den goda nyheten är att allt – databasen, lagringen och UUID-hanteringen – kan integreras perfekt 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 PHP och Composer uppdaterade och skapa ett nytt projekt eller använd ett befintligt. Från konsolen genererar du helt enkelt projektet med det typiska Laravel-kommandot och börjar sedan konfigurera anslutningen.

När du väl har projektets skelett är det vanliga steget att installera ett enkelt autentiseringssystem. Laravel Breeze passar mycket bra in eftersom det inkluderar Bladmallar och grundläggande inloggnings- och registreringsflödeDetta gör att du snabbt kan verifiera 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-panel och skapa ett nytt databasprojekt (du kan göra detta direkt från databas.ny(som omdirigerar till guiden). Om du inte har ett konto än ser du först registreringsskärmen; om du redan har ett går du direkt till projektinställningarna och avsnittet där du kan kontrollera anslutningssträngen.

På projektsidan, i anslutningsavsnittet, hittar du en knapp som "Anslut" eller liknande. När du klickar på den visar Supabase flera anslutningssträngformat (URI, individuella parametrar etc.). Kopiera hela URI:n, men kom ihåg att du måste ersätt lösenordet för den du faktiskt använder i databasen, eftersom en standardvärde 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 fullsträngformatet. Målet är att allt ska peka på Supabase Postgres-kluster och inte till din lokala värd.

Konfigurera Postgres-drivrutinen och Supabase-schemat i Laravel

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

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

'pgsql' => ,

Nyckeln här ligger i parametern sökvägSupabase använder som standard det publika schemat, 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 framgår av föregående exempel.

På så sätt skapas migreringar och tabeller som genereras av ditt projekt i det alternativa schemat och inte offentligt. Denna separation gör hanteringen mycket enklare. säkerhetsregler, RLS och åtkomst från Supabase-panelen utan att trampa på något du inte borde och hålla databasstrukturen organiserad.

När du har justerat konfigurationsfilen kan du starta migreringarna med de vanliga Laravel-kommandona. Detta skapar autentiseringstabellerna och alla andra tabeller du har definierat. Om allt är korrekt konfigurerat kommer kommandona att köras mot Supabase Postgres utan att du behöver göra något annat.

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 fungerar. kommunicera korrekt med Supabase och du kan fortsätt bygga din affärslogik i vanliga fall.

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 beteendet hos PostgreSQL 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 sökgrammatik optimerad för den specifika Supabase-miljön.

När den är installerad kan du deklarera något liknande följande inom anslutningssektion:

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

Fördelen med att använda den här drivrutinen är att du fortfarande får all kraft från Postgres-motorn, men den hanterar också automatiskt vissa känsliga detaljer i Supabase, särskilt när man arbetar med UUID:er som primärnycklar eller relationsfältDetta undviker att manuellt skriva casting för varje komplicerad 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, 12.x och med PHP från version 8.1 och framåt, såväl som vilken vanlig PostgreSQL-databas som helst, 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ö. 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 ger oväntade resultatI ett "vanligt" Postgres-system skulle man kunna lösa detta med globala omvandlingar eller anpassade operatorer, men i Supabase är dessa globala anpassningar inte tillåtna.

Detta antyder än en direkt undersökning av stilen:

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

Det kommer inte att fungera som du förväntar dig. Men om du utför den explicita rollbesättningen:

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

Frågan lyckades. Problemet är att i Laravel, när man skriver frågor med Eloquent eller frågebyggaren, vill man inte gå sätta CAST i varje varDet är där supabase-drivrutinen från det tidigare nämnda paketet kommer in i bilden, som tar hand om att lägga till dessa rollbesättningar å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 konsultationer, utan också i förenarOm du till exempel vill hämta inlägg och koppla dem till användartabellen 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();

Föraren är ansvarig för att tillämpa rollbesättningar behövs för att texta i relevanta UUID-kolumner, transparent. 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 modellklassen och definiera en skyddad array med 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 UUID som standard, och den lägger till alla kolumner du deklarerar i egenskapen. $uuidColumns och kommunicerar den informationen till frågebyggaren så att den vet var konverteringarna ska tillämpas. Således blir all dataåtkomst som involverar UUID:er konsekvent och automatiserad.

För ännu mer avancerade fallDu kan registrera en anpassad UUID-kolumndetektor. Med PostgresGrammar-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 aktiverad kan systemet betrakta som UUID:er alla kolumner vars namn har ett visst mönster eller finns inom en specifik lista, och anpassa sig till mycket specifika namngivningskonventioner av 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 Laravel-disk med FlysystemFör detta ändamål finns det en specifik adapter som gör att Supabase Storage kan behandlas som bara en annan drivrutin i config/filesystems.php.

Paketet i fråga tillhandahåller en Flysystem-adapter som integreras transparent med ramverkets lagringssystem. Den uppfyller minimikraven för PHP >= 8.1, Laravel 10.x eller 11.x och PHP fileinfo-ändelsen (ext-fileinfo), som Laravel redan 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/filsystem.phpInom arraydiskarna skulle du lägga till något liknande följande:

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

Bucketparametern är vanligtvis helt enkelt namn på lagringshinken som du skapade i Supabase-panelen (till exempel myapp-file-uploads). Slutpunkten är bas-URL:en för projektets lagringstjänst, som också syns i motsvarande avsnitt i panelen, och härleds vanligtvis från projektets URL och region.

Alternativet `public` anger om hinkens innehåll 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 belastningen. säkerhet och komfort 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 röra den om du använder en proxy eller mellanliggande CDN och du vill att de genererade vägarna ska peka till 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 felkonfigurerad nyckel.

På supabase-disken för config/filesystems.php nämner konfigurationen att man använder en "privilegierad nyckel" i nyckelfältet, vilket uttryckligen anger att en skrivskyddad nyckel inte fungerar. Det betyder att du måste använda en servicenyckel som har skrivbehörighet på bucketen, inte bara en publik API-nyckel avsedd för klienten eller en nyckel avsedd för S3-kompatibilitet utan modifieringsbehörigheter.

I Supabase-panelen, i avsnittet API och lagringskonfiguration, hittar du både de anonyma nycklarna och service_role eller motsvarandeDet här är de som har utökade behörigheter. Det är den servicenyckeln, och inte den publika, som du ska placera i variabeln SUPABASE_SECRET_ACCESS_KEY, som drivrutinen sedan läser igenom env('SUPABASE_SECRET_ACCESS_KEY').

Om du har testat med S3-nyckeln från lagringskonfigurationen eller med de generiska API-nycklarna från projektet är det mycket troligt att dessa autentiseringsuppgifter inte har behörighet att skriva till den specifika bucketen, vilket resulterar i skrivfelet. Ändra nyckelvärdet till en giltig servicenyckel med skrivbehörighet Och genom att bekräfta att hinken existerar och är korrekt skriven, är problemet vanligtvis löst.

Utöver nyckeln ä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, till exempel ett extra tecken eller en felaktig domän, kan förhindra att adaptern fungerar. hitta filernas faktiska destination.

Arbetsflöde med Laravel Breeze, Blade och Supabase Storage

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

Inom dina kontroller skulle du använda Förvaringsfasad pekar på 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 i stil med:

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

Denna kod anger att Laravel ska använda disken supabas och placera filen i den virtuella uppladdningsmappen i den konfigurerade bucketen. Om nyckeln och slutpunkten är korrekta laddas filen 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 justera config/filesystems.php och miljövariablerna, utan att vidröra affärslogiken.

Genom att kombinera detta med Blade och Breeze kan du erbjuda uppladdningsformulär, fillistor och nedladdningslänkar som är 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 se eller ladda ner.

Hela detta ekosystem av paket, drivrutiner och konfigurationer gör att Laravel kan arbeta mycket bekvämt med Supabase, både inom relationsdata med Postgres och i... fillagring och UUID-hanteringGenom att justera nycklar, scheman och drivrutiner korrekt uppnår du en mycket solid integration som undviker många av de typiska fel som uppstår när man försöker ansluta båda plattformarna manuellt och utan dessa lager av hjälp.

Genom att ansluta Laravel till Supabase för databas och lagring, utnyttja den dedikerade Supabase-drivrutinen för att hantera UUID:er sömlöst och använda Flysystem-adaptern för lagring kan du bygga moderna applikationer där Hela den komplexa infrastrukturen är inkapslad Bakom kulisserna på Laravels rena API, från migreringar och autentisering till uppladdning av filer till säkra buckets.