Kako integrirati Supabase z Laravelom za bazo podatkov in shranjevanje

Informatec Digital » Viri » Kako integrirati Supabase z Laravelom za baze podatkov in shranjevanje

Če delate z Laravelom in ste predani programiranju v zaledju ter želite preiti na sodobno, upravljano bazo podatkov PostgreSQL, kot je Supabase , ste verjetno ugotovili, da zgolj spreminjanje nekaj spremenljivk v datoteki .env ni dovolj. Obstajajo podrobnosti povezave, sheme, preverjanje pristnosti in shranjevanje datotek, ki lahko, če jih zanemarite, privedejo do precej skrivnostnih napak.

Poleg tega, ko želite iti še korak dlje in uporabiti Supabase kot shrambo datotek, integrirano z Laravelovim diskovnim sistemom (Storage), se stvari nekoliko zapletejo: servisni ključi, vedra, končne točke, gonilniki Flysystem po meri itd. Dobra novica je, da je mogoče vse popolnoma integrirati – bazo podatkov, shrambo in upravljanje UUID-ov – na dokaj čist način.

Povezovanje Laravela z bazo podatkov Supabase

Prvi korak je imeti delujoč Laravel projekt in ga povezati z bazo podatkov Postgres, ki jo zagotavlja Supabase. Za to potrebujete okolje s posodobljenim PHP in Composerjem , ustvarite pa lahko nov projekt ali uporabite obstoječega. V konzoli preprosto ustvarite projekt s standardnim Laravelovim ukazom in nato začnite z vzpostavljanjem povezave.

Ko je ogrodje projekta postavljeno, je običajna praksa namestitev preprostega sistema za preverjanje pristnosti. Laravel Breeze se zelo dobro ujema, saj vključuje predloge Blade in osnovni postopek prijave in registracije , kar vam omogoča hitro preverjanje, ali je povezava z vašo bazo podatkov pravilno konfigurirana in ali lahko brez težav ustvarjate uporabnike.

Če želite pridobiti podrobnosti o povezavi, se prijavite v nadzorno ploščo Supabase in ustvarite nov projekt baze podatkov (to lahko storite neposredno iz `database.new` , ki vas preusmeri na čarovnika). Če še nimate računa, boste najprej videli zaslon za registracijo; če ga že imate, boste šli neposredno v nastavitve projekta in razdelek, kjer najdete niz za povezavo.

Na strani projekta, v razdelku za povezavo, boste našli gumb »Poveži se« ali nekaj podobnega. S klikom nanj se bo prikazalo več oblik povezovalnih nizov (URI, posamezni parametri itd.). Kopirajte celoten URI, vendar ne pozabite zamenjati gesla z geslom, ki ga dejansko uporabljate za bazo podatkov, saj se pogosto prikaže privzeto geslo ali nadomestno besedilo.

S temi informacijami morate iti v datoteko .env vašega projekta Laravel in posodobiti spremenljivke DB_HOST, DB_PORT, DB_DATABASE, DB_USERNAME in DB_PASSWORD ali konfigurirati spremenljivko DATABASE_URL, če želite uporabiti celoten format niza. Cilj je zagotoviti, da vse kaže na gručo Supabase Postgres in ne na vaš lokalni strežnik.

Konfigurirajte gonilnik Postgres in shemo Supabase v Laravelu

V Laravelu je ključna datoteka za konfiguracijo baze podatkov config/database.php . Čeprav lahko neposredno uporabite gonilnik pgsql, ki je priložen ogrodju, je pri delu s Supabase običajno uporabiti nekatere dodatne nastavitve, zlasti glede shem in možnosti, specifičnih za Postgres.

Tipična konfiguracija Postgresa v Laravelu bi lahko izgledala takole, znotraj polja connections, pod ključem 'pgsql' :

'pgsql' => ,

Ključ se skriva v parametru `search_path` . Supabase privzeto uporablja shemo `public`, ki je izpostavljena prek svojih API-jev. Če želite svojo aplikacijo Laravel ločiti od te sheme in se izogniti konfliktom tabel ali pravilnikov, je zelo priporočljivo, da `search_path` spremenite v svojo shemo, na primer `laravel` , kot je prikazano v prejšnjem primeru.

Na ta način bodo migracije in tabele, ki jih generira vaš projekt, ustvarjene v tej alternativni shemi in ne javno. Ta ločitev močno poenostavi upravljanje varnostnih pravil, RLS in dostopa iz nadzorne plošče Supabase, ne da bi prepisali karkoli ne bi smeli, hkrati pa ohranite organizirano strukturo baze podatkov.

Ko prilagodite konfiguracijsko datoteko, lahko zaženete migracije s standardnimi Laravel ukazi. S tem boste ustvarili tabele za preverjanje pristnosti in vse druge tabele, ki ste jih definirali. Če je vse pravilno konfigurirano, se bodo ukazi samodejno zagnali na strežniku Supabase Postgres.

Ko so migracije končane, zaženite razvojni strežnik z ukazom `artisan serve` in poskusite registrirati in prijaviti uporabnike. Če se ne pojavijo napake pri povezavi ali migraciji, to pomeni, da Laravel pravilno komunicira s Supabase in lahko nadaljujete z gradnjo poslovne logike kot običajno.

Uporaba specifičnega gonilnika Supabase v Laravelu

Čeprav standardni gonilnik pgsql deluje, obstaja paket, ki doda gonilnik baze podatkov supabase za Laravel in s tem razširja delovanje PostgreSQL z zelo uporabnimi izboljšavami, zlasti glede ravnanja s stolpci UUID in načina konstruiranja poizvedb.

Ta paket, ki se distribuira kot prahsys/laravel-supabase, se namesti prek programa Composer in registrira dodaten gonilnik z imenom supabase, ki ga lahko uporabite v datoteki config/database.php. Notranje temelji na gonilniku Postgres za Laravel, vendar vključuje nastavitve in slovnice poizvedb, optimizirane za specifično okolje Supabase.

Ko je nameščen, lahko v razdelku connections deklarirate nekaj takega :

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

Prednost uporabe tega gonilnika je, da še vedno dobite polno moč mehanizma Postgres, hkrati pa samodejno obravnava tudi nekatere občutljive podrobnosti Supabase, zlasti pri delu z UUID-ji kot primarnimi ključi ali polji za relacije . S tem se izognete ročnemu pisanju pretvorbe v vsaki zapleteni poizvedbi.

Paket je zasnovan tako, da se dobro ujema s sodobnimi različicami ogrodja in PHP-ja, saj ponuja uradno združljivost z Laravel 10.x, 11.x in 12.x ter s PHP od različice 8.1 naprej, pa tudi s katero koli standardno podatkovno bazo PostgreSQL, vključno s Supabase.

Da bi zagotovili pravilno delovanje, paket vključuje nabor avtomatiziranih testov. Teste lahko zaženete z ukazom `composer test`, ki bo za hitrost uporabil pomnilniško bazo podatkov SQLite, ali pa pripravite datoteko `.env.testing`, ki kaže na vašo bazo Supabase, in zaženete `composer test-supabase`, da preverite delovanje v resničnem okolju z oddaljenim Postgresom.

Upravljanje UUID-jev v Supabase in Laravel

Supabase ima posebnost s stolpci UUID: če poskušate UUID primerjati neposredno z besedilnim nizom brez pretvorbe, lahko poizvedba ne uspe ali pa vrne nepričakovane rezultate . V golem okolju Postgres bi to lahko rešili z globalnimi pretvorbami ali operatorji po meri, vendar Supabase ne dovoljuje takšnih globalnih prilagoditev.

To pomeni , da neposredno povpraševanje po slogu:

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

Ne bo delovalo , kot bi morda pričakovali. Če pa izvedete eksplicitno pretvorbo:

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

Poizvedba je uspešna. Težava je v tem, da v Laravelu, ko pišete poizvedbe z Eloquentom ali graditeljem poizvedb, ne želite dodati CAST-ov vsakemu stavku WHERE . Tukaj pride prav gonilnik supabase iz prej omenjenega paketa, ki te pretvorbe doda namesto vas.

Ko je ta gonilnik aktiven, lahko izvajate pogosta vprašanja, kot so:

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

In ne samo v neposrednih poizvedbah, ampak tudi v združitvah . Če želite na primer pridobiti objave in jih združiti s tabelo uporabnikov z uporabo polja UUID, lahko storite nekaj takega:

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

Gonilnik pregledno obravnava uporabo potrebnih besedilnih pretvorb v ustrezne stolpce UUID. Na ta način vaša koda ostane idiomatična za Laravel in vam ni treba pisati surovega SQL-a ali uporabljati čudnih trikov v vsaki zapleteni poizvedbi.

Če želite natančnejši nadzor nad tem, kateri stolpci se štejejo za UUID-je, paket ponuja lastnost CastsUuidColumns za vaše modele Eloquent. Preprosto jo uporabite v svojem razredu modela in definirajte zaščiteno polje dodatnih stolpcev:

use Prahsys\Supabase\Traits\CastsUuidColumns;

class Post extends Model
{
    use CastsUuidColumns;

    protected $uuidColumns = ;
}

Ta lastnost naredi tri pomembne stvari: vključi primarni ključ kot privzeti UUID, doda vse stolpce, ki jih deklarirate, lastnosti `$uuidColumns` in te informacije sporoči graditelju poizvedb, da ve, kje uporabiti pretvorbe. Zaradi tega je ves dostop do podatkov, ki vključuje UUID-je, dosleden in avtomatiziran.

Za še bolj napredne primere lahko registrirate detektor stolpcev UUID po meri. Z uporabo PostgresGrammarja iz paketa lahko določite funkcijo povratnega klica, ki na podlagi imena stolpca ali konteksta poizvedbe odloči, ali naj se obravnava kot UUID. Na primer:

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

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

S to funkcijo lahko sistem kot UUID upošteva vse stolpce, katerih ime ima določen vzorec ali je znotraj določenega seznama, s čimer se prilagodi zelo specifičnim konvencijam poimenovanja vašega projekta.

Integrirajte Supabase Storage kot datotečni sistem v Laravel

Poleg baze podatkov morajo številni projekti shranjevati slike, dokumente ali druge datoteke, ki jih naložijo uporabniki. Supabase vključuje storitev shranjevanja v vedrih, ki jo lahko uporabite kot Laravelov disk prek Flysystema . Na voljo je poseben adapter, ki shrambo Supabase obravnava kot dodaten gonilnik znotraj config/filesystems.php.

Zadevni paket ponuja adapter Flysystem, ki se brezhibno integrira s sistemom za shranjevanje ogrodja. Izpolnjuje minimalne zahteve PHP >= 8.1, Laravel 10.x in 11.x ter pripono PHP fileinfo (ext-fileinfo), ki jo Laravel običajno priporoča za delo z datotekami. Namestitev se izvede s programom Composer, ko pa je vključen, morate v konfiguraciji le še definirati disk supabase.

V datoteki config/filesystems.php , znotraj polja disks, bi dodali nekaj podobnega naslednjemu:

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

Parameter `bucket` je običajno preprosto ime vedra za shranjevanje, ki ste ga ustvarili v nadzorni plošči Supabase (na primer `myapp-file-uploads`). `Končna točka` je osnovni URL storitve shranjevanja projekta, ki je viden tudi v ustreznem razdelku nadzorne plošče in je običajno izpeljan iz URL-ja in regije projekta.

Možnost `public` določa, ali bo vsebina vedra privzeto obravnavana kot javna. Če je vrednost `true`, bo adapter ustvaril dostopne URL-je brez posebnega podpisa; če je vrednost `false`, se uporabi možnost `defaultUrlGeneration`, ki lahko vsili ustvarjanje podpisanih URL-jev s časom poteka, določenim z `signedUrlExpires`. Ta konfiguracija vam omogoča uravnoteženje varnosti in udobja glede na vrsto datotek, ki jih obravnavate.

Splošni URL diska je običajno puščen kot nič, tako da ga adapter samodejno izpelje iz končne točke. Spremenite ga le, če uporabljate posredniški proxy ali CDN in želite, da ustvarjene poti kažejo na to domeno namesto na izvorno domeno Supabase.

Odpravljanje napak pri nalaganju in razumevanje ključa Supabase Storage

Precej pogosta težava pri poskusu nalaganja datotek v Supabase Storage iz Laravela je prejemanje sporočil, kot je »Datoteke ni mogoče zapisati na lokacijo: nalaganja/…« . To običajno pomeni, da Supabase kljub konfiguraciji gonilnika zavrača operacijo pisanja zaradi nezadostnih dovoljenj ali napačne konfiguracije ključa.

V konfiguracijski datoteki diska supabase, `config/filesystems.php`, konfiguracija v polju `key` določa uporabo "privilegiranega ključa" , kar izrecno navaja, da ključ samo za branje ne bo deloval. To pomeni, da morate uporabiti servisni ključ z dovoljenji za pisanje v vedro, ne le javnega ključa API na strani odjemalca ali ključa združljivosti S3 brez dovoljenj za spreminjanje.

V plošči Supabase, v razdelku za konfiguracijo API-ja in shrambe, boste našli tako anonimne ključe kot ključe service_role (ali njihove ekvivalente) , ki imajo razširjene privilegije. Ta storitveni ključ, ne javnega, morate vstaviti v spremenljivko SUPABASE_SECRET_ACCESS_KEY, ki jo bo gonilnik nato prebral z uporabo env('SUPABASE_SECRET_ACCESS_KEY').

Če ste testirali s ključem S3 iz konfiguracije shrambe ali s generičnimi ključi API projekta, je zelo verjetno, da te poverilnice nimajo dovoljenj za pisanje v določeno vedro, kar povzroči napako pri pisanju. Težavo običajno odpravite s spremembo vrednosti ključa v veljaven ključ storitve z dovoljenji za pisanje in potrditvijo, da vedro obstaja in je pravilno poimenovano.

Poleg gesla je pomembno preveriti, ali se vedro, definirano v SUPABASE_STORAGE_BUCKET, natančno ujema z vedrom, ustvarjenim v vmesniku Supabase, pri čemer se upoštevajo velike in male črke, in ali končna točka ustreza pravilnemu URL-ju za ta primerek shrambe. Podrobnosti, kot je dodaten znak ali napačna domena, lahko preprečijo adapterju, da bi našel dejanski cilj datotek.

Delovni potek z Laravel Breeze, Blade in Supabase Storage

Ko konfigurirate bazo podatkov in shrambo, je naslednji logičen korak integracija vsega z vmesnikom Laravel Breeze in predlogami Blade . Na ta način se lahko uporabniki registrirajo, overjajo in nalagajo datoteke v Supabase, ne da bi zapustili ekosistem Laravel.

Znotraj vaših krmilnikov bi uporabili fasado shranjevanja, ki kaže na disk supabase. Na primer, za nalaganje datoteke, prejete iz obrazca z vnosom datoteke, bi lahko naredili nekaj takega:

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

Ta koda Laravelu naroči, naj uporabi disk Supabase in datoteko namesti v mapo za navidezne nalaganja znotraj konfiguriranega vedra. Če sta ključ in končna točka pravilna, bo datoteka naložena v shrambo Supabase in lahko pridobite njeno pot ali ustvarite javne ali podpisane URL-je z uporabo standardnih metod shranjevanja.

Prednost tega pristopa je, da vaša aplikacija vzdržuje en sam vmesnik za shranjevanje, ne glede na to, ali uporablja lokalni disk, Amazon S3, Supabase ali drugo podprto storitev. Zamenjava ponudnika se zmanjša na prilagajanje config/filesystems.php in okoljskih spremenljivk, ne da bi to vplivalo na poslovno logiko.

Z združitvijo tega z Blade in Breeze lahko ponudite obrazce za nalaganje, sezname datotek in povezave za prenos, ki so popolnoma integrirani v uporabniško izkušnjo vaše aplikacije. Poleg tega vam pristop Supabase Storage, ki temelji na vedrih in pravilnikih, omogoča, da izkoristite njegove kontrole dostopa in varnostna pravila za določitev, kaj si lahko posamezni uporabnik ogleda ali prenese.

Celoten ekosistem paketov, gonilnikov in konfiguracij omogoča Laravelu brezhibno delovanje s Supabase, tako glede relacijskih podatkov s Postgresom kot tudi shranjevanja datotek in upravljanja UUID-jev . S pravilno konfiguracijo ključev, shem in gonilnikov dosežete zelo robustno integracijo, ki se izogne ​​številnim tipičnim napakam, do katerih pride pri poskusu ročne povezave obeh platform brez teh podpornih plasti.

Povezovanje Laravela s Supabase za bazo podatkov in shranjevanje, uporaba namenskega gonilnika Supabase za upravljanje UUID-jev brez glavobolov in uporaba adapterja Flysystem za shranjevanje vam omogoča gradnjo sodobnih aplikacij, kjer je vsa kompleksna infrastruktura združena za čistim Laravelovim API-jem, od migracij in preverjanja pristnosti do nalaganja datotek v varne vedra.