Sådan integrerer du Supabase med Laravel til database og lagring

Informatic Digital » Recursos » Sådan integrerer du Supabase med Laravel til database og lagring

Hvis du arbejder med Laravel og er dedikeret til backend-programmering , og du ønsker at tage springet til en moderne, administreret PostgreSQL- database som Supabase , har du sikkert indset, at det ikke er nok blot at ændre et par variabler i .env-filen. Der er forbindelsesdetaljer, skemaer, godkendelse og fillagring, som, hvis de forsømmes, kan føre til nogle ret kryptiske fejl.

Derudover, når man vil gå et skridt videre og bruge Supabase som fillagring integreret med Laravels disksystem (Storage), bliver tingene lidt mere komplicerede: servicenøgler, buckets, endpoints, brugerdefinerede Flysystem-drivere osv. Den gode nyhed er, at alt kan integreres perfekt – databasen, lagringen og UUID-håndteringen – på en forholdsvis overskuelig måde.

Forbinder Laravel til Supabase-databasen

Det første trin er at have et fungerende Laravel-projekt og linke det til Postgres-databasen leveret af Supabase. Til dette skal du bruge et miljø med opdateret PHP og Composer , og du kan oprette et nyt projekt eller bruge et eksisterende. Fra konsollen skal du blot generere projektet ved hjælp af standard Laravel-kommandoen og derefter begynde at konfigurere forbindelsen.

Når du har projektets framework på plads, er den sædvanlige praksis at installere et simpelt godkendelsessystem. Laravel Breeze passer rigtig godt ind, fordi det inkluderer Blade-skabeloner og et grundlæggende login- og registreringsflow , så du hurtigt kan validere, at din databaseforbindelse er korrekt konfigureret, og at du kan oprette brugere uden problemer.

For at få forbindelsesoplysningerne skal du logge ind på dit Supabase-dashboard og oprette et nyt databaseprojekt (du kan gøre dette direkte fra `database.new` , som omdirigerer til guiden). Hvis du ikke har en konto endnu, vil du først se tilmeldingsskærmen. Hvis du allerede har en, går du direkte til projektindstillingerne og det afsnit, hvor du kan finde forbindelsesstrengen.

På projektsiden, i forbindelsessektionen, finder du en "Opret forbindelse" -knap eller noget lignende. Hvis du klikker på den, vises flere formater for forbindelsesstrenge (URI, individuelle parametre osv.). Kopier hele URI'en, men husk at erstatte adgangskoden med den, du rent faktisk bruger til databasen, da der ofte vises en standardadgangskode eller pladsholder.

Med disse oplysninger skal du gå til dit Laravel-projekts .env-fil og opdatere variablerne DB_HOST, DB_PORT, DB_DATABASE, DB_USERNAME og DB_PASSWORD, eller konfigurere variablen DATABASE_URL, hvis du foretrækker at bruge det fulde strengformat. Målet er at sikre, at alt peger på Supabase Postgres-klyngen og ikke på din localhost.

Konfigurer Postgres-driveren og Supabase-skemaet i Laravel

I Laravel er nøglefilen til databasekonfiguration config/database.php . Selvom du direkte kan bruge den pgsql-driver, der følger med frameworket, er det almindeligt at anvende nogle yderligere indstillinger, når man arbejder med Supabase, især med hensyn til skemaer og Postgres-specifikke indstillinger.

En typisk Postgres-konfiguration i Laravel kan se sådan ud, inden for connections-arrayet, under nøglen 'pgsql' :

'pgsql' => ,

Nøglen her ligger i parameteren `search_path` . Supabase bruger som standard skemaet `public`, som er det skema, der eksponeres gennem dets API'er. Hvis du vil holde din Laravel-applikation adskilt fra dette skema og undgå tabel- eller politikkonflikter, anbefales det kraftigt at ændre `search_path` til dit eget skema, for eksempel `laravel` , som set i det foregående eksempel.

På denne måde vil migreringer og tabeller genereret af dit projekt blive oprettet i dette alternative skema og ikke offentligt. Denne adskillelse forenkler i høj grad administrationen af ​​sikkerhedsregler, RLS og adgang fra Supabase-panelet uden at overskrive noget, du ikke burde, samtidig med at databasestrukturen holdes organiseret.

Når du har justeret konfigurationsfilen, kan du køre migreringerne ved hjælp af standard Laravel-kommandoer. Dette vil oprette autentificeringstabellerne og alle andre tabeller, du har defineret. Hvis alt er konfigureret korrekt, vil kommandoerne automatisk køre mod Supabase Postgres-serveren .

Når migreringerne er fuldført, skal du starte udviklingsserveren med `artisan serve` og prøve at registrere og logge brugere ind. Hvis der ikke vises nogen forbindelses- eller migreringsfejl, betyder det, at Laravel kommunikerer korrekt med Supabase , og du kan fortsætte med at bygge din forretningslogik som sædvanligt.

Brug af en specifik Supabase-driver i Laravel

Selvom standard pgsql-driveren fungerer, er der en pakke, der tilføjer en supabase-databasedriver til Laravel , hvilket udvider PostgreSQLs funktionsmåde med meget nyttige forbedringer, især med hensyn til håndteringen af ​​UUID-kolonner og den måde, forespørgsler konstrueres på.

Denne pakke, distribueret som prahsys/laravel-supabase, installeres via Composer og registrerer en ekstra driver kaldet supabase, som du kan bruge i din config/database.php-fil. Internt er den baseret på Laravels Postgres-driver, men inkorporerer indstillinger og forespørgselsgrammatikker, der er optimeret til det specifikke Supabase-miljø.

Når det er installeret, kan du angive noget i retning af følgende i forbindelsesafsnittet :

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

Fordelen ved at bruge denne driver er, at du stadig får den fulde kraft fra Postgres-motoren, men den håndterer også automatisk visse følsomme Supabase-detaljer, især når du arbejder med UUID'er som primære nøgler eller relationsfelter . Dette undgår at skulle skrive casting manuelt i hver kompleks forespørgsel.

Pakken er også designet til at passe godt til moderne versioner af frameworket og PHP, og tilbyder officiel kompatibilitet med Laravel 10.x, 11.x og 12.x og med PHP fra version 8.1 og fremefter, samt enhver standard PostgreSQL-database, inklusive naturligvis Supabase.

For at sikre at alt fungerer korrekt, indeholder pakken en række automatiserede tests. Du kan køre testene med kommandoen `composer test`, som bruger en SQLite-database i hukommelsen for at opnå hastighed, eller du kan forberede en `.env.testing`-fil, der peger på din Supabase, og køre `composer test-supabase` for at verificere opførslen i et virkeligt miljø med fjern Postgres.

UUID-styring i Supabase og Laravel

Supabase har en ejendommelighed med UUID-kolonner: hvis du forsøger at sammenligne en UUID direkte med en tekststreng uden at bruge casting, kan forespørgslen mislykkes eller returnere uventede resultater . I et rent Postgres-miljø kunne du løse dette med globale casting-operatorer eller brugerdefinerede operatorer, men Supabase tillader ikke sådanne globale tilpasninger.

Dette indebærer , at en direkte forespørgsel på stilen:

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

Det vil ikke fungere som forventet. Men hvis du udfører den eksplicitte casting:

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

Forespørgslen er vellykket. Problemet er, at når du skriver forespørgsler med Eloquent eller forespørgselsbyggeren i Laravel, ønsker du ikke at tilføje CAST'er til hver WHERE-klausul . Det er her, supabase-driveren fra den førnævnte pakke kommer ind i billedet, som tilføjer disse casts for dig.

Når driveren er aktiv, kan du udføre almindelige forespørgsler såsom:

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

Og ikke kun i direkte forespørgsler, men også i joins . Hvis du for eksempel vil hente indlæg og joine dem med brugertabellen ved hjælp af et UUID-felt, kan du gøre noget i retning af dette:

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

Driveren håndterer transparent anvendelsen af ​​de nødvendige tekstkonverteringer til de relevante UUID-kolonner. På denne måde forbliver din kode idiomatisk for Laravel, og du behøver ikke at skrive rå SQL eller bruge mærkelige tricks i hver kompleks forespørgsel.

Hvis du ønsker bedre kontrol over, hvilke kolonner der betragtes som UUID'er, tilbyder pakken CastsUuidColumns- egenskaben til dine Eloquent-modeller. Brug den blot i din modelklasse og definer et beskyttet array af yderligere kolonner:

use Prahsys\Supabase\Traits\CastsUuidColumns;

class Post extends Model
{
    use CastsUuidColumns;

    protected $uuidColumns = ;
}

Denne egenskab gør tre vigtige ting: den inkluderer den primære nøgle som standard UUID, tilføjer alle kolonner, du deklarerer, til egenskaben `$uuidColumns` , og kommunikerer disse oplysninger til forespørgselsbyggeren, så den ved, hvor casts skal anvendes. Dette gør al dataadgang, der involverer UUID'er, ensartet og automatiseret.

I endnu mere avancerede tilfælde kan du registrere en brugerdefineret UUID-kolonnedetektor. Ved at bruge PostgresGrammar fra pakken kan du angive en callback-funktion, der baseret på kolonnenavnet eller forespørgselskonteksten afgør, om den skal behandles som en UUID. For eksempel:

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

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

Med denne funktion konfigureret kan systemet betragte alle kolonner som UUID, hvis navn har et bestemt mønster eller er inden for en specifik liste, og tilpasse sig meget specifikke navngivningskonventioner for dit projekt.

Integrer Supabase Storage som et filsystem i Laravel

Ud over databasen skal mange projekter gemme billeder, dokumenter eller andre filer, der er uploadet af brugere. Supabase inkluderer en bucket-baseret lagringstjeneste, som du kan bruge som Laravels disk via Flysystem . En specifik adapter er tilgængelig til at behandle Supabase Storage som en ekstra driver i config/filesystems.php.

Den pågældende pakke leverer en Flysystem-adapter, der integreres problemfrit med frameworkets Storage-system. Den opfylder minimumskravene for PHP >= 8.1, Laravel 10.x og 11.x samt PHP fileinfo-udvidelsen (ext-fileinfo), som Laravel typisk anbefaler til filhåndtering. Installationen udføres ved hjælp af Composer, og når den er inkluderet, behøver du kun at definere supabase-disken i konfigurationen.

I filen config/filesystems.php , i disks-arrayet, skal du tilføje noget i stil med følgende:

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

Parameteren `bucket` er normalt blot navnet på den storage-bucket, du oprettede i Supabase-dashboardet (for eksempel `myapp-file-uploads`). `Endpoint` er basis-URL'en for projektets storage-tjeneste, som også er synlig i den tilsvarende sektion af dashboardet, og er normalt afledt af projektets URL og region.

Indstillingen `public` angiver, om bucketens indhold som standard skal behandles som offentligt. Hvis `true`, genererer adapteren tilgængelige URL'er uden en særlig signatur; hvis `false`, aktiveres indstillingen `defaultUrlGeneration`, som kan tvinge generering af signerede URL'er med en udløbstid angivet af `signedUrlExpires`. Denne konfiguration giver dig mulighed for at afbalancere sikkerhed og bekvemmelighed afhængigt af den type filer, du håndterer.

Den generelle disk-URL efterlades normalt som null, så adapteren automatisk udleder den fra slutpunktet. Du bør kun ændre den, hvis du bruger en mellemliggende proxy eller CDN og ønsker, at de genererede ruter skal pege på det pågældende domæne i stedet for det native Supabase-domæne.

Foretag fejlfinding ved upload, og forstå nøglen til Supabase Storage

Et ret almindeligt problem, når man forsøger at uploade filer til Supabase Storage fra Laravel, er at modtage meddelelser som "Kan ikke skrive filen på placeringen: uploads/..." . Dette indikerer normalt, at selvom driveren er konfigureret, nægter Supabase skriveoperationen på grund af utilstrækkelige tilladelser eller en forkert nøglekonfiguration.

I supabase-diskkonfigurationsfilen, `config/filesystems.php`, specificerer konfigurationen brugen af ​​en "privilegeret nøgle" i `key`-feltet, hvilket eksplicit angiver, at en skrivebeskyttet nøgle ikke vil fungere. Det betyder, at du skal bruge en servicenøgle med skrivetilladelser til bucket'en, ikke blot en offentlig API-nøgle på klientsiden eller en S3-kompatibilitetsnøgle uden ændringstilladelser.

I Supabase-panelet, i afsnittet API- og lagerkonfiguration, finder du både anonyme nøgler og service_role-nøgler (eller deres tilsvarende) , som har udvidede rettigheder. Det er denne servicenøgle, ikke den offentlige, som du skal placere i SUPABASE_SECRET_ACCESS_KEY-variablen, som driveren derefter læser ved hjælp af env('SUPABASE_SECRET_ACCESS_KEY').

Hvis du har testet med S3-nøglen fra lagerkonfigurationen eller med projektets generiske API-nøgler, er det meget sandsynligt, at disse legitimationsoplysninger ikke har skrivetilladelser til den specifikke bucket, hvilket resulterer i skrivefejlen. Ændring af nøgleværdien til en gyldig servicenøgle med skrivetilladelser og bekræftelse af, at bucket'en findes og er korrekt navngivet, løser normalt problemet.

Ud over adgangskoden er det vigtigt at kontrollere, at den bucket, der er defineret i SUPABASE_STORAGE_BUCKET, nøjagtigt matcher den, der er oprettet i Supabase-grænsefladen, med respekt for store og små bogstaver, og at slutpunktet svarer til den korrekte URL for den pågældende lagringsinstans. En detalje, såsom et ekstra tegn eller et forkert domæne, kan forhindre adapteren i at finde filernes faktiske destination.

Arbejdsgang med Laravel Breeze, Blade og Supabase Storage

Når du har konfigureret din database og lagerplads, er det næste logiske trin at integrere alt med din Laravel Breeze-grænseflade og Blade-skabeloner . På denne måde kan brugerne registrere, godkende og uploade filer til Supabase uden at forlade Laravel-økosystemet.

I dine controllere ville du bruge Storage-facaden, der peger på Supabase-disken. For eksempel, for at uploade en fil modtaget fra en formular med et filinput, kan du gøre noget i retning af dette:

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

Denne kode fortæller Laravel, at den skal bruge Supabase- disken og placere filen i den virtuelle uploadmappe i den konfigurerede bucket. Hvis nøglen og slutpunktet er korrekte, uploades filen til Supabase-lageret, og du kan hente dens sti eller generere offentlige eller signerede URL'er ved hjælp af standardlagringsmetoder.

Fordelen ved denne tilgang er, at din applikation har en enkelt grænseflade til lagring, uanset om den bruger en lokal disk, Amazon S3, Supabase eller en anden understøttet tjeneste. Skift af udbyder reduceres til at justere config/filesystems.php og miljøvariabler uden at påvirke forretningslogikken.

Ved at kombinere dette med Blade og Breeze kan du tilbyde uploadformularer, fillister og downloadlinks, der er fuldt integreret i din applikations brugeroplevelse. Derudover giver Supabase Storages bucket- og policybaserede tilgang dig mulighed for at udnytte adgangskontroller og sikkerhedsregler til at definere, hvad hver bruger kan se eller downloade.

Hele dette økosystem af pakker, drivere og konfigurationer gør det muligt for Laravel at arbejde problemfrit med Supabase, både med hensyn til relationelle data med Postgres og fillagring og UUID-administration . Ved korrekt konfiguration af nøgler, skemaer og drivere opnår du en meget robust integration, der undgår mange af de typiske fejl, der opstår, når man forsøger at forbinde begge platforme manuelt uden disse understøttende lag.

Ved at forbinde Laravel med Supabase til database og lagring, udnytte den dedikerede Supabase-driver til at administrere UUID'er uden hovedpine og bruge Flysystem-adapteren til lagring, kan du bygge moderne applikationer, hvor al den komplekse infrastruktur er indkapslet bag Laravels rene API, fra migreringer og godkendelse til upload af filer til sikre buckets.