Slik integrerer du Supabase med Laravel for database og lagring

Informatec Digital » Ressurser » Slik integrerer du Supabase med Laravel for database og lagring

Hvis du jobber med Laravel og er dedikert til backend-programmering og du har lyst til å ta spranget til en database moderne, administrert PostgreSQL som SupabaseDu har sikkert lagt merke til at det ikke er nok å bare endre et par variabler i .env-filen. Det finnes tilkoblingsdetaljer, skjemaer, autentisering og fillagring som, hvis de neglisjeres, kan føre til noen ganske kryptiske feil.

Videre, når du vil gå et skritt videre og bruke Supabase som fillagring Når det integreres med Laravels lagringssystem, blir ting litt mer komplekse: servicenøkler, buckets, endepunkter, tilpassede Flysystem-drivere osv. Den gode nyheten er at alt – databasen, lagringen og UUID-håndteringen – kan integreres perfekt på en ganske ren måte.

Koble Laravel til Supabase-databasen

Det første steget er å ha et fungerende Laravel-prosjekt og koble det til Postgres-databasen levert av Supabase. For dette trenger du et miljø med PHP og Composer oppdatert og opprett et nytt prosjekt eller bruk et eksisterende. Fra konsollen genererer du ganske enkelt prosjektet med den typiske Laravel-kommandoen og begynner deretter å sette opp tilkoblingen.

Når du har prosjektets skjelett, er det vanlige trinnet å installere et enkelt autentiseringssystem. Laravel Breeze passer veldig bra inn fordi det inkluderer Bladmaler og grunnleggende innloggings- og registreringsprosessDette lar deg raskt bekrefte at databasetilkoblingen din er riktig konfigurert, og at du kan opprette brukere uten problemer.

For å få tak i tilkoblingsdetaljene, logg inn på Supabase-panelet ditt og opprett et nytt databaseprosjekt (du kan gjøre dette direkte fra database.ny(som omdirigerer til veiviseren). Hvis du ikke har en konto ennå, vil du først se registreringsskjermen. Hvis du allerede har en, går du direkte til prosjektinnstillingene og delen der du kan sjekke tilkoblingsstrengen.

På prosjektsiden, i tilkoblingsdelen, finner du en knapp som "Connect" eller lignende. Når du klikker på den, viser Supabase deg flere formater for tilkoblingsstrenger (URI, individuelle parametere osv.). Kopier hele URI-en, men husk at du må erstatt passordet for den du faktisk bruker i databasen, siden en standardverdi eller en plassholder ofte vises.

Med den informasjonen må du gå til Laravel-prosjektets .env-fil og oppdatere variablene DB_HOST, DB_PORT, DB_DATABASE, DB_USERNAME og DB_PASSWORD, eller konfigurere variabelen DATABASE_URL hvis du foretrekker å bruke fullstrengformatet. Målet er at alt skal peke til Supabase Postgres-klynge og ikke til din lokale vert.

Konfigurer Postgres-driveren og Supabase-skjemaet i Laravel

I Laravel er nøkkelfilen for databasekonfigurasjon config/database.phpSelv om du kan bruke pgsql-driveren som følger med rammeverket direkte, er det vanlig å bruke noen ekstra justeringer når man jobber med Supabase, spesielt når det gjelder skjemaer og Postgres-spesifikke alternativer.

En typisk konfigurasjon for Postgres i Laravel kan se slik ut, innenfor tilkoblingsarrayet, under nøkkelen 'pgsql':

'pgsql' => ,

Nøkkelen her ligger i parameteren søkestiSupabase bruker som standard det offentlige skjemaet, som er det som eksponeres gjennom API-ene. Hvis du vil holde Laravel-applikasjonen din separat fra det skjemaet og unngå tabell- eller policykonflikter, anbefales det på det sterkeste å endre search_path til ditt eget skjema, for eksempel. laravel, som vist i det forrige eksemplet.

På denne måten vil migreringer og tabeller generert av prosjektet ditt bli opprettet i det alternative skjemaet og ikke offentlig. Denne separasjonen gjør administrasjonen mye enklere. sikkerhetsregler, RLS og tilgang fra Supabase-panelet uten å tråkke på noe du ikke burde, og holde databasestrukturen organisert.

Når du har justert konfigurasjonsfilen, kan du starte migreringene ved hjelp av de vanlige Laravel-kommandoene. Dette vil opprette autentiseringstabellene og eventuelle andre tabeller du har definert. Hvis alt er riktig konfigurert, vil kommandoene kjøre mot Supabase Postgres uten at du trenger å gjøre noe annet.

Når migreringene er fullført, start utviklingsserveren med `artisan serve` og prøv å registrere og logge inn brukere. Hvis det ikke vises noen tilkoblings- eller migreringsfeil, betyr det at Laravel fungerer. kommuniserer riktig med Supabase og det kan du fortsett å bygge forretningslogikken din normalt.

Bruk av en spesifikk Supabase-driver i Laravel

Selv om standard pgsql-driveren fungerer, finnes det en pakke som legger til en Supabase-databasedriver for Laravel, og utvider virkemåten til PostgreSQL med svært nyttige forbedringer, spesielt når det gjelder håndteringen av UUID-kolonner og måten spørringer konstrueres på.

Denne pakken, distribuert som prahsys/laravel-supabase, installeres via Composer og registrerer en ekstra driver kalt supabase som du kan bruke i config/database.php-filen din. Internt er den basert på Laravels Postgres-driver, men inneholder innstillinger og oppslagsgrammatikker optimalisert for det spesifikke Supabase-miljøet.

Når den er installert, kan du deklarere noe som følgende i tilkoblingsseksjon:

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

Fordelen med å bruke denne driveren er at du fortsatt får all kraften fra Postgres-motoren, men den håndterer også automatisk visse delikate detaljer i Supabase, spesielt når du jobber med UUID-er som primærnøkler eller relasjonsfeltDette unngår å måtte skrive casting manuelt for hver kompliserte spørring.

Pakken er også designet for å passe godt med moderne versjoner av rammeverket og PHP, og tilbyr offisiell kompatibilitet med Laravel 10.x, 11.x, 12.x og med PHP fra versjon 8.1 og utover, samt enhver standard PostgreSQL-database, inkludert selvfølgelig Supabase.

For å sikre at alt fungerer som det skal, inneholder pakken en rekke automatiserte tester. Du kan kjøre testene med kommandoen `composer test`, som bruker en SQLite-database i minnet for å øke hastigheten, eller du kan forberede en `.env.testing`-fil som peker til Supabase-filen din og kjøre `composer test-supabase` for å bekrefte oppførselen i et virkelig miljø. Ekstern Postgres.

UUID-administrasjon i Supabase og Laravel

Supabase har en særegenhet med UUID-kolonner: hvis du prøver å sammenligne en UUID direkte med en tekststreng uten å bruke casting, kan det hende at spørringen mislykkes eller returnerer uventede resultaterI et "vanlig" Postgres-system kan du løse dette med globale konverteringer eller tilpassede operatorer, men i Supabase er ikke disse globale tilpasningene tillatt.

Dette innebærer enn en direkte undersøkelse av stilen:

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

Det vil ikke fungere som du forventer. Men hvis du utfører den eksplisitte castingen:

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

Spørringen er vellykket. Problemet er at i Laravel, når du skriver spørringer med Eloquent eller spørrebyggeren, vil du ikke gå å sette CAST i hver hvorDet er der supabase-driveren fra den nevnte pakken kommer inn i bildet, som tar seg av å legge til disse rollebesetningene for deg.

Med den driveren aktiv kan du utføre vanlige spørsmål som:

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

Og ikke bare i direkte konsultasjoner, men også i tiltrerHvis du for eksempel vil hente innlegg og koble dem til brukertabellen ved hjelp av et UUID-felt, kan du gjøre noe slikt:

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

Sjåføren er ansvarlig for å anvende rollebesetninger trengs for tekst i de relevante UUID-kolonnene, transparent. På denne måten forblir koden din idiomatisk for Laravel, og du trenger ikke å skrive rå SQL eller bruke rare triks i hver kompleks spørring.

Hvis du ønsker bedre kontroll over hvilke kolonner som regnes som UUID-er, tilbyr pakken egenskapen AvstøpningerUuid-kolonner for dine Eloquent-modeller. Bare bruk den i modellklassen og definer en beskyttet matrise med ekstra kolonner:

use Prahsys\Supabase\Traits\CastsUuidColumns;

class Post extends Model
{
    use CastsUuidColumns;

    protected $uuidColumns = ;
}

Denne egenskapen gjør tre viktige ting: den inkluderer primærnøkkelen som UUID som standard, og den legger til enhver kolonne du deklarerer i egenskapen. $uuidKolonner og kommuniserer denne informasjonen til spørrebyggeren slik at den vet hvor den skal bruke konverteringene. Dermed blir all datatilgang som involverer UUID-er konsekvent og automatisert.

For enda mer avanserte tilfellerDu kan registrere en tilpasset UUID-kolonnedetektor. Ved hjelp av PostgresGrammar-pakken kan du spesifisere en tilbakeringingsfunksjon som, basert på kolonnenavnet eller spørrekonteksten, avgjø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 funksjonen er aktivert, kan systemet anse som UUID-er alle kolonner med navn som har et bestemt mønster eller er innenfor en spesifikk liste, og tilpasse seg svært spesifikke navnekonvensjoner av prosjektet ditt.

Integrer Supabase Storage som et filsystem i Laravel

I tillegg til databasen må mange prosjekter lagre bilder, dokumenter eller andre filer lastet opp av brukere. Supabase inkluderer en bøttebasert lagringstjeneste som du kan bruke som Laravel-disk ved bruk av FlysystemFor dette formålet finnes det en spesifikk adapter som tillater at Supabase Storage behandles som bare en annen driver i config/filesystems.php.

Pakken det gjelder tilbyr en Flysystem-adapter som integreres transparent med rammeverkets lagringssystem. Den oppfyller minimumskravene til PHP >= 8.1, Laravel 10.x eller 11.x og PHP fileinfo-utvidelsen (ext-fileinfo), som Laravel allerede anbefaler for håndtering av filer. Installasjonen gjøres med Composer, og når den er inkludert, trenger du bare å definere supabase-disken i konfigurasjonen.

I filen config/filsystemer.phpInnenfor array-diskene legger du til noe som ligner på følgende:

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

Bøtteparameteren er vanligvis ganske enkelt navn på lagringsbøtte som du opprettet i Supabase-panelet (for eksempel myapp-file-uploads). Endepunktet er basis-URL-en til prosjektets lagringstjeneste, som også er synlig i den tilsvarende delen av panelet, og er vanligvis avledet fra prosjektets URL-adresse og region.

Alternativet `public` angir om innholdet i bøtta skal behandles som offentlig som standard. Hvis `true`, vil adapteren generere tilgjengelige URL-er uten en spesiell signatur. Hvis `false`, aktiveres alternativet `defaultUrlGeneration`, som kan tvinge frem generering av signerte URL-er med en utløpstid spesifisert av `signedUrlExpires`. Denne konfigurasjonen lar deg balansere belastningen. sikkerhet og komfort avhengig av hvilken type filer du håndterer.

Den generelle disk-URL-en blir vanligvis stående som null, slik at adapteren automatisk henter den fra endepunktet. Du bør bare berøre den hvis du bruker en proxy eller mellomliggende CDN og du vil at de genererte rutene skal peke til det domenet i stedet for det opprinnelige Supabase-domenet.

Feilsøk opplastingsfeil og forstå nøkkelen til Supabase Storage

Et ganske vanlig problem når man prøver å laste opp filer til Supabase Storage fra Laravel, er å motta meldinger som «Kan ikke skrive filen på plasseringen: uploads/…»Dette indikerer vanligvis at selv om driveren er konfigurert, nekter Supabase skriveoperasjonen på grunn av utilstrekkelige tillatelser eller en feilkonfigurert nøkkel.

På supabase-disken til config/filesystems.php nevner konfigurasjonen bruk av en «privilegert nøkkel» i nøkkelfeltet, og angi eksplisitt at en skrivebeskyttet nøkkel ikke vil fungere. Dette betyr at du må bruke en tjenestenøkkel som har skriverettigheter på bøtta, ikke bare en offentlig API-nøkkel beregnet for klienten eller en nøkkel beregnet for S3-kompatibilitet uten modifikasjonstillatelser.

I Supabase-panelet, i API- og lagringskonfigurasjonsdelen, finner du både de anonyme nøklene og service_role eller tilsvarendeDette er de med utvidede rettigheter. Det er denne tjenestenøkkelen, og ikke den offentlige, som du skal plassere i SUPABASE_SECRET_ACCESS_KEY-variabelen, som driveren deretter vil lese gjennom env('SUPABASE_SECRET_ACCESS_KEY').

Hvis du har testet med S3-nøkkelen fra lagringskonfigurasjonen eller med de generiske API-nøklene fra prosjektet, er det svært sannsynlig at disse påloggingsinformasjonene ikke har tillatelse til å skrive til den spesifikke bøtta, noe som resulterer i skrivefeilen. Endring av nøkkelverdien til en gyldig tjenestenøkkel med skriverettigheter Og ved å bekrefte at bøtta eksisterer og er riktig skrevet, er problemet vanligvis løst.

I tillegg til nøkkelen er det viktig å bekrefte at bøtta som er definert i SUPABASE_STORAGE_BUCKET samsvarer nøyaktig med den som er opprettet i Supabase-grensesnittet, med respekt for store og små bokstaver, og at endepunktet samsvarer med riktig URL for den lagringsinstansen. En detalj, for eksempel et ekstra tegn eller et feil domene, kan forhindre at adapteren fungerer. finn den faktiske destinasjonen til filene.

Arbeidsflyt med Laravel Breeze, Blade og Supabase Storage

Når du har satt opp databasen og lagringen, er det neste naturlige trinnet å integrere alt med Laravel Breeze-grensesnitt og Blade-malerPå denne måten kan brukere registrere, autentisere og laste opp filer til Supabase uten å forlate Laravel-økosystemet.

Innenfor kontrollerne dine ville du bruke Lagringsfasade peker til supabase-disken. For eksempel, for å laste opp en fil mottatt fra et skjema med en filinndata, kan du gjøre noe slikt:

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

Denne koden forteller Laravel at den skal bruke disken supabase og plasser filen i den virtuelle opplastingsmappen i den konfigurerte bøtta. Hvis nøkkelen og endepunktet er riktige, lastes filen opp til Supabase-lagring, og du kan hente banen eller generere offentlige eller signerte URL-er ved hjelp av standard lagringsmetoder.

Fordelen med denne tilnærmingen er at applikasjonen din opprettholder ett enkelt grensesnitt for lagring, uavhengig av om den bruker lokal disk, Amazon S3, Supabase eller en annen støttet tjeneste. Bytte av leverandør reduseres til juster config/filesystems.php og miljøvariablene, uten å berøre forretningslogikken.

Ved å kombinere dette med Blade og Breeze kan du tilby opplastingsskjemaer, fillister og nedlastingslenker som er fullt integrert i applikasjonens brukeropplevelse. I tillegg lar Supabase Storages bøtte- og policybaserte tilnærming deg utnytte dens tilgangskontroller og sikkerhetsregler for å definere hva hver bruker kan se eller laste ned.

Hele dette økosystemet av pakker, drivere og konfigurasjoner lar Laravel jobbe veldig komfortabelt med Supabase, både når det gjelder relasjonsdata med Postgres og i... fillagring og UUID-administrasjonVed å justere nøklene, skjemaene og driverne riktig, oppnår du en svært solid integrasjon som unngår mange av de typiske feilene som oppstår når man prøver å koble til begge plattformene manuelt og uten disse lagene med assistanse.

Ved å koble Laravel til Supabase for database og lagring, utnytte den dedikerte Supabase-driveren for å administrere UUID-er sømløst, og bruke Flysystem-adapteren for lagring, kan du bygge moderne applikasjoner der Hele den komplekse infrastrukturen er innkapslet Bak kulissene til Laravels rene API, fra migreringer og autentisering til opplasting av filer til sikre buckets.