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 har lyst til at tage springet til en database moderne, administreret PostgreSQL som SupabaseDu har sikkert bemærket, 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.

Desuden, når du vil gå et skridt videre og bruge Supabase som fillagring Når det integreres med Laravels storage-system, bliver tingene lidt mere komplekse: servicenøgler, buckets, endpoints, brugerdefinerede Flysystem-drivere osv. Den gode nyhed er, at alt – databasen, storage og UUID-håndtering – kan integreres perfekt på en forholdsvis ren måde.

Forbinder Laravel til Supabase-databasen

Det første skridt er at have et fungerende Laravel-projekt og linke det til Postgres-databasen leveret af Supabase. Til dette skal du bruge et miljø med PHP og Composer opdateret og opret et nyt projekt eller brug et eksisterende. Fra konsollen skal du blot generere projektet med den typiske Laravel-kommando og derefter begynde at konfigurere forbindelsen.

Når du har projektets skelet, er det sædvanlige trin at installere et simpelt autentificeringssystem. Laravel Breeze passer rigtig godt ind, fordi det inkluderer Blad skabeloner og grundlæggende login- og registreringsprocesDette giver dig mulighed for hurtigt at kontrollere, 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-panel og oprette et nyt databaseprojekt (du kan gøre dette direkte fra database.ny(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 tjekke forbindelsesstrengen.

På projektsiden, i forbindelsessektionen, finder du en knap som "Tilslut" eller lignende. Når du klikker på den, viser Supabase dig flere formater for forbindelsesstrenge (URI, individuelle parametre osv.). Kopier den komplette URI, men husk at du skal udskift adgangskoden for den, du rent faktisk bruger i databasen, da der ofte vises en standardkode eller en 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 alt peger på Supabase Postgres-klynge og ikke til din lokale vært.

Konfigurer Postgres-driveren og Supabase-skemaet i Laravel

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

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

'pgsql' => ,

Nøglen her ligger i parameteren søgestiSupabase bruger som standard det offentlige skema, 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 f.eks. dit eget skema. laravel, som set i det foregående eksempel.

På denne måde vil migreringer og tabeller genereret af dit projekt blive oprettet i det alternative skema og ikke offentligt. Denne adskillelse gør administrationen meget nemmere. sikkerhedsregler, RLS og adgang fra Supabase-panelet uden at træde på noget, du ikke bør, og holde databasestrukturen organiseret.

Når du har justeret konfigurationsfilen, kan du starte migreringerne ved hjælp af de sædvanlige Laravel-kommandoer. Dette vil oprette autentificeringstabellerne og eventuelle andre tabeller, du har defineret. Hvis alt er konfigureret korrekt, vil kommandoerne køre mod Supabase Postgres uden at du behøver at gøre noget andet.

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 fungerer. kommunikation korrekt med Supabase og du kan Fortsæt med at opbygge din forretningslogik normalt.

Brug af en specifik Supabase-driver i Laravel

Selvom standard pgsql-driveren virker, er der en pakke, der tilføjer en Supabase-databasedriver til Laravel, der 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 opslagsgrammatikker optimeret til det specifikke Supabase-miljø.

Når den er installeret, kan du deklarere noget i retning af følgende i forbindelsessektion:

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

Fordelen ved at bruge denne driver er, at du stadig får al kraften fra Postgres-motoren, men den håndterer også automatisk visse delikate detaljer i Supabase, især når du arbejder med UUID'er som primære nøgler eller relationsfelterDette undgår at skulle skrive casting manuelt for hver kompliceret 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, 12.x og med PHP fra version 8.1 og fremefter, såvel som 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 øge hastigheden, 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ø. 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 caste, kan forespørgslen muligvis mislykkes eller returnerer uventede resultaterI et "almindeligt" Postgres-system kunne man løse dette med globale casts eller brugerdefinerede operatorer, men i Supabase er disse globale tilpasninger ikke tilladt.

Dette indebærer end en direkte undersøgelse af stilen:

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

Det vil ikke virke som du ville forvente. 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 man skriver forespørgsler med Eloquent eller forespørgselsbyggeren i Laravel, vil man ikke gå sætter CAST i hvert stedDet er her, supabase-driveren fra den førnævnte pakke kommer i spil, som tager sig af at tilføje disse casts for dig.

Med den driver aktiv kan du udføre almindelige forespørgsler som:

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

Og ikke kun i direkte konsultationer, men også i slutterHvis du for eksempel vil hente indlæg og forbinde 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', 'test@example.com')
    ->get();

Chaufføren er ansvarlig for at anvende rollebesætninger nødvendige til tekst i de relevante UUID-kolonner, transparent. 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 egenskaben CastsUuidColumns til dine Eloquent-modeller. Brug den blot i modelklassen 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 som standard den primære nøgle som UUID, og ​​den tilføjer enhver kolonne, du deklarerer i egenskaben. $uuidKolonner og kommunikerer disse oplysninger til forespørgselsbyggeren, så den ved, hvor castningerne skal anvendes. Således bliver al dataadgang, der involverer UUID'er konsistent og automatiseret.

For endnu mere avancerede tilfældeDu kan registrere en brugerdefineret UUID-kolonnedetektor. Ved hjælp af PostgresGrammar-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, );
});

Når denne funktion er etableret, kan systemet betragte alle kolonner, hvis navn har et bestemt mønster eller er inden for en specifik liste, som UUID'er og tilpasse sig meget specifikke navngivningskonventioner af 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 udnytte som Laravel-disk ved hjælp af FlysystemTil dette formål er der en specifik adapter, der tillader, at Supabase Storage behandles som blot en anden driver i config/filesystems.php.

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

I filen config/filsystemer.phpInden for array-diskene skal du tilføje noget i stil med følgende:

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

Bucket-parameteren er normalt blot navn på lagerbeholder som du oprettede i Supabase-panelet (f.eks. myapp-file-uploads). Slutpunktet er basis-URL'en for projektets lagringstjeneste, som også er synlig i den tilsvarende sektion af panelet, 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 frem generering af signerede URL'er med en udløbstid angivet af `signedUrlExpires`. Denne konfiguration giver dig mulighed for at afbalancere belastningen. sikkerhed og komfort afhængigt af hvilken type filer du håndterer.

Den generelle disk-URL efterlades normalt som null, så adapteren automatisk udleder den fra slutpunktet. Du bør kun røre den, hvis du bruger en proxy eller mellemliggende CDN og du ønsker, at de genererede ruter skal pege på det 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 beskeder 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 konfigureret nøgle.

På supabase-disken i config/filesystems.php nævner konfigurationen brugen af en "privilegeret nøgle" i nøglefeltet, hvor det eksplicit anføres, at en skrivebeskyttet nøgle ikke vil fungere. Det betyder, at du skal bruge en servicenøgle, der har skrivetilladelser på bucket'en, ikke blot en offentlig API-nøgle beregnet til klienten eller en nøgle beregnet til S3-kompatibilitet uden ændringstilladelser.

I Supabase-panelet, i afsnittet API- og lagerkonfiguration, finder du både de anonyme nøgler og service_role eller tilsvarendeDisse er dem med udvidede rettigheder. Det er den servicenøgle, og ikke den offentlige, som du skal placere i SUPABASE_SECRET_ACCESS_KEY-variablen, som driveren derefter vil læse igennem env('SUPABASE_SECRET_ACCESS_KEY').

Hvis du har testet med S3-nøglen fra lagerkonfigurationen eller med de generiske API-nøgler fra projektet, er det meget sandsynligt, at disse legitimationsoplysninger ikke har tilladelse til at skrive til den specifikke bucket, hvilket resulterer i skrivefejlen. Ændring af nøgleværdien til en gyldig servicenøgle med skrivetilladelser Og ved at bekræfte, at bucket'en eksisterer og er korrekt skrevet, er problemet normalt løst.

Ud over nøglen 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 fungere. find den faktiske destination for filerne.

Arbejdsgang med Laravel Breeze, Blade og Supabase Storage

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

Inden for dine controllere ville du bruge Opbevaringsfacade 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:

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

Denne kode fortæller Laravel at bruge disken supabase og placer 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 juster config/filesystems.php og miljøvariablerne, uden at røre 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 policy-baserede tilgang dig mulighed for at udnytte dens adgangskontrol og sikkerhedsregler 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 meget komfortabelt med Supabase, både i relationsdataaspektet med Postgres og i... fillagring og UUID-styringVed at justere nøgler, skemaer og drivere korrekt opnår du en meget solid integration, der undgår mange af de typiske fejl, der opstår, når man forsøger at forbinde begge platforme manuelt og uden disse lag af assistance.

Ved at forbinde Laravel med Supabase til database og lagring, udnytte den dedikerede Supabase-driver til problemfri administration af UUID'er og bruge Flysystem-adapteren til lagring, kan du bygge moderne applikationer, hvor Hele den komplekse infrastruktur er indkapslet Bag kulisserne på Laravels rene API, fra migreringer og godkendelse til upload af filer til sikre buckets.