Kaip integruoti „Supabase“ su „Laravel“ duomenų bazei ir saugyklai

Informatec Digital » Ištekliai » Kaip integruoti „Supabase“ su „Laravel“ duomenų bazei ir saugyklai

Jei dirbate su „Laravel“ ir esate atsidavę serverio programavimui , ir norite pereiti prie modernios, valdomos „PostgreSQL“ duomenų bazės, tokios kaip „Supabase“ , tikriausiai supratote, kad nepakanka tiesiog pakeisti kelis kintamuosius .env faile. Yra ryšio detalių, schemų, autentifikavimo ir failų saugojimo, kurie, jei nepaisoma, gali sukelti gana paslaptingų klaidų.

Be to, kai norite žengti dar vieną žingsnį ir naudoti „Supabase“ kaip failų saugyklą, integruotą su „Laravel“ diskų sistema („Storage“), viskas tampa šiek tiek sudėtingiau: paslaugų raktai, saugyklos, galiniai taškai, pasirinktiniai „Flysystem“ tvarkyklės ir kt. Geros žinios yra tai, kad viską galima puikiai integruoti – duomenų bazę, saugyklą ir UUID tvarkymą – gana švariu būdu.

„Laravel“ prijungimas prie „Supabase“ duomenų bazės

Pirmas žingsnis – sukurti veikiantį „Laravel“ projektą ir susieti jį su „Supabase“ teikiama „Postgres“ duomenų baze. Tam reikia aplinkos su atnaujinta PHP ir „Composer“ , galite sukurti naują projektą arba naudoti esamą. Konsolėje tiesiog sugeneruokite projektą naudodami standartinę „Laravel“ komandą ir pradėkite ryšio nustatymą.

Sukūrus projekto sistemą, įprasta praktika yra įdiegti paprastą autentifikavimo sistemą. „Laravel Breeze“ puikiai tinka, nes joje yra „Blade“ šablonai ir pagrindinis prisijungimo bei registracijos procesas , leidžiantis greitai patikrinti, ar jūsų duomenų bazės ryšys tinkamai sukonfigūruotas, ir ar galite be problemų kurti vartotojus.

Norėdami gauti ryšio informaciją, prisijunkite prie „Supabase“ valdymo skydelio ir sukurkite naują duomenų bazės projektą (tai galite padaryti tiesiogiai iš `database.new` , kuris nukreipia į vedlį). Jei dar neturite paskyros, pirmiausia pamatysite registracijos ekraną; jei jau turite, pateksite tiesiai į projekto nustatymus ir skyrių, kuriame rasite ryšio eilutę.

Projekto puslapyje, ryšio skiltyje, rasite mygtuką „Prisijungti“ arba panašų. Jį spustelėjus bus rodomi keli ryšio eilutės formatai (URI, atskiri parametrai ir kt.). Nukopijuokite visą URI, tačiau nepamirškite slaptažodžio pakeisti tuo, kurį naudojate duomenų bazei, nes dažnai rodomas numatytasis slaptažodis arba vietos žymeklis.

Turėdami šią informaciją, turite atidaryti savo „Laravel“ projekto .env failą ir atnaujinti kintamuosius DB_HOST, DB_PORT, DB_DATABASE, DB_USERNAME ir DB_PASSWORD arba sukonfigūruoti kintamąjį DATABASE_URL, jei norite naudoti visą eilutės formatą. Tikslas – užtikrinti, kad viskas nukreiptų į „ Supabase Postgres“ klasterį , o ne į jūsų vietinį serverį.

Konfigūruokite „Postgres“ tvarkyklę ir „Supabase“ schemą „Laravel“

„Laravel“ sistemoje pagrindinis duomenų bazės konfigūracijos failas yra „config/database.php“ . Nors galite tiesiogiai naudoti „pgsql“ tvarkyklę, kuri pateikiama kartu su sistema, dirbant su „Supabase“ įprasta taikyti kai kuriuos papildomus nustatymus, ypač susijusius su schemomis ir „Postgres“ specifinėmis parinktimis.

Tipinė „Postgres“ konfigūracija „Laravel“ aplinkoje gali atrodyti taip, jungčių masyve, po raktu „pgsql“ :

'pgsql' => ,

Esmė čia slypi parametre „search_path“ . Pagal numatytuosius nustatymus „Supabase“ naudoja „viešąją“ schemą, kuri yra prieinama per jos API. Jei norite, kad jūsų „Laravel“ programa būtų atskirta nuo šios schemos ir išvengtumėte lentelių ar politikos konfliktų, labai rekomenduojama pakeisti „search_path“ į savo schemą, pavyzdžiui, „laravel“ , kaip parodyta ankstesniame pavyzdyje.

Tokiu būdu jūsų projekto sugeneruotos migracijos ir lentelės bus kuriamos šioje alternatyvioje schemoje, o ne viešai. Šis atskyrimas labai supaprastina saugumo taisyklių, RLS ir prieigos iš „Supabase“ skydelio valdymą neperrašant nieko nereikalingo, tuo pačiu išlaikant tvarkingą duomenų bazės struktūrą.

Sureguliavus konfigūracijos failą, galite vykdyti migracijas naudodami standartines „Laravel“ komandas. Tai sukurs autentifikavimo lenteles ir visas kitas jūsų apibrėžtas lenteles. Jei viskas sukonfigūruota teisingai, komandos automatiškai bus vykdomos „Supabase Postgres“ serveryje .

Baigę migraciją, paleiskite kūrimo serverį naudodami komandą „artisan serve“ ir pabandykite užregistruoti bei prisijungti naudotojus. Jei nerodoma jokių ryšio ar migracijos klaidų, tai reiškia, kad „Laravel“ tinkamai bendrauja su „Supabase“ ir galite tęsti savo verslo logikos kūrimą kaip įprasta.

Naudojant specialų „Supabase“ tvarkyklę „Laravel“ sistemoje

Nors standartinė „pgsql“ tvarkyklė veikia, yra paketas, kuris prideda „Laravel“ skirtą „supabase“ duomenų bazės tvarkyklę , praplečiančią „PostgreSQL“ veikimą labai naudingais patobulinimais, ypač susijusiais su UUID stulpelių tvarkymu ir užklausų konstravimo būdu.

Šis paketas, platinamas kaip „prahsys/laravel-supabase“, įdiegiamas naudojant „Composer“ ir užregistruoja papildomą tvarkyklę, vadinamą „supabase“, kurią galite naudoti savo config/database.php faile. Viduje jis pagrįstas „Laravel“ „Postgres“ tvarkykle, tačiau apima nustatymus ir užklausų gramatiką, optimizuotą konkrečiai „Supabase“ aplinkai.

Įdiegę, jungčių skiltyje galite deklaruoti kažką panašaus į šį :

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

Šios tvarkyklės naudojimo privalumas yra tas, kad vis tiek gaunate visą „Postgres“ variklio galią, tačiau ji taip pat automatiškai tvarko tam tikrą subtilią „Supabase“ informaciją, ypač dirbant su UUID kaip pirminiais raktais arba ryšių laukais . Tai leidžia išvengti rankinio peradresavimo į skirtingas puses kiekvienoje sudėtingoje užklausoje.

Paketas taip pat sukurtas taip, kad gerai veiktų su šiuolaikinėmis sistemos ir PHP versijomis, siūlant oficialų suderinamumą su „Laravel 10.x“, „11.x“ ir „12.x“ bei su PHP nuo 8.1 versijos, taip pat su bet kuria standartine „PostgreSQL“ duomenų baze, įskaitant, žinoma, „Supabase“.

Siekiant užtikrinti, kad viskas veiktų tinkamai, pakete yra automatizuotų testų rinkinys. Testus galite paleisti naudodami komandą „composer test“, kuri greičiui padidinti naudos atmintyje esančią SQLite duomenų bazę, arba galite paruošti failą „.env.testing“, nukreipiantį į jūsų „Supabase“, ir paleisti komandą „composer test-supabase“, kad patikrintumėte veikimą realioje aplinkoje su nuotoliniu „Postgres“.

UUID valdymas „Supabase“ ir „Laravel“

„Supabase“ turi ypatybę su UUID stulpeliais: jei bandysite palyginti UUID tiesiogiai su teksto eilute be konvertavimo, užklausa gali nepavykti arba pateikti netikėtus rezultatus . Griežtoje „Postgres“ aplinkoje tai galite išspręsti naudodami globalius konvertavimus arba pasirinktinius operatorius, tačiau „Supabase“ neleidžia tokių globalių pritaikymų.

Tai reiškia , kad tiesioginė stiliaus užklausa:

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

Tai neveiks taip, kaip tikėtumėtės. Tačiau jei atliksite tiesioginį aktorių perdavimą:

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

Užklausa sėkminga. Problema ta, kad „Laravel“ sistemoje, rašant užklausas naudojant „Eloquent“ arba užklausų kūrimo priemonę, nenorite pridėti CAST prie kiekvienos WHERE sąlygos . Čia praverčia „supabase“ tvarkyklė iš minėto paketo, kuri prideda šiuos pakeitimus už jus.

Kai tvarkyklė aktyvi, galite atlikti įprastas užklausas , pvz.:

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

Ir ne tik tiesioginėse užklausose, bet ir sujungimuose . Pavyzdžiui, jei norite gauti įrašus ir sujungti juos su naudotojų lentele naudodami UUID lauką, galite atlikti tokius veiksmus:

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

Tvarkyklė skaidriai tvarko reikiamų teksto modifikacijų taikymą atitinkamiems UUID stulpeliams. Tokiu būdu jūsų kodas išlieka idiomatiškas „Laravel“ ir jums nereikia rašyti neapdoroto SQL ar naudoti keistų gudrybių kiekvienoje sudėtingoje užklausoje.

Jei norite tiksliau kontroliuoti, kurie stulpeliai laikomi UUID, paketas siūlo „ CastsUuidColumns“ savybę jūsų „Eloquent“ modeliams. Tiesiog naudokite ją savo modelio klasėje ir apibrėžkite apsaugotą papildomų stulpelių masyvą:

use Prahsys\Supabase\Traits\CastsUuidColumns;

class Post extends Model
{
    use CastsUuidColumns;

    protected $uuidColumns = ;
}

Ši funkcija atlieka tris svarbius dalykus: ji įtraukia pirminį raktą kaip numatytąjį UUID, prideda visus jūsų deklaruojamus stulpelius prie `$uuidColumns` savybės ir perduoda šią informaciją užklausų kūrimo įrankiui, kad jis žinotų, kur taikyti modifikacijas. Tai užtikrina, kad visa prieiga prie duomenų, susijusi su UUID, būtų nuosekli ir automatizuota.

Dar sudėtingesniais atvejais galite užregistruoti pasirinktinį UUID stulpelių detektorių. Naudodami paketo „PostgresGrammar“, galite nurodyti grįžtamojo ryšio funkciją, kuri, remdamasi stulpelio pavadinimu arba užklausos kontekstu, nusprendžia, ar jis turėtų būti laikomas UUID. Pavyzdžiui:

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

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

Nustačius šią funkciją, sistema gali laikyti UUID visus stulpelius, kurių pavadinimai atitinka tam tikrą šabloną arba yra konkrečiame sąraše, prisitaikydama prie labai specifinių jūsų projekto pavadinimų suteikimo konvencijų .

Integruokite „Supabase Storage“ kaip failų sistemą „Laravel“

Be duomenų bazės, daugelyje projektų reikia saugoti vaizdus, ​​dokumentus ar kitus vartotojų įkeltus failus. „Supabase“ apima talpyklų pagrindu veikiančią saugojimo paslaugą, kurią galite naudoti kaip „Laravel“ diską per „Flysystem“ . Yra specialus adapteris, skirtas „Supabase Storage“ apdoroti kaip papildomą tvarkyklę faile config/filesystems.php.

Aptariamas paketas pateikia „Flysystem“ adapterį, kuris sklandžiai integruojasi su platformos saugojimo sistema. Jis atitinka minimalius PHP >= 8.1, „Laravel 10.x“ ir „11.x“ reikalavimus bei PHP „fileinfo“ plėtinį (ext-fileinfo), kurį „Laravel“ paprastai rekomenduoja failų tvarkymui. Diegimas atliekamas naudojant „Composer“, o įtraukus, konfigūracijoje tereikia apibrėžti „supabase“ diską.

Faile config/filesystems.php , diskų masyve, reikėtų pridėti kažką panašaus į šį:

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

Parametras „bucket“ paprastai yra tiesiog „Supabase“ ataskaitų srityje sukurtos saugyklos talpyklos pavadinimas (pvz., „myapp-file-uploads“). „endpoint“ yra projekto saugyklos paslaugos bazinis URL, taip pat matomas atitinkamame ataskaitų srities skyriuje ir paprastai gaunamas iš projekto URL ir regiono.

Parinktis „public“ nurodo, ar talpyklos turinys pagal numatytuosius nustatymus bus laikomas viešu. Jei „true“, adapteris generuos prieinamus URL be specialaus parašo; jei „false“, įsijungia parinktis „defaultUrlGeneration“, kuri gali priverstinai generuoti pasirašytus URL su galiojimo laiku, nurodytu parametru „signedUrlExpires“. Ši konfigūracija leidžia subalansuoti saugumą ir patogumą, atsižvelgiant į tvarkomų failų tipą.

Bendras disko URL paprastai paliekamas kaip nulinis, kad adapteris jį automatiškai gautų iš galinio taško. Jį turėtumėte modifikuoti tik tuo atveju, jei naudojate tarpinį tarpinį serverį arba CDN ir norite, kad sugeneruoti maršrutai nukreiptų į tą domeną, o ne į vietinį „Supabase“ domeną.

Įkėlimo klaidų šalinimas ir „Supabase Storage“ esmės supratimas

Gana dažna problema bandant įkelti failus į „Supabase Storage“ iš „Laravel“ yra gaunami pranešimai, tokie kaip „Nepavyko įrašyti failo į vietą: įkėlimai/…“ . Tai paprastai reiškia, kad nors tvarkyklė sukonfigūruota, „Supabase“ neleidžia rašyti dėl nepakankamų leidimų arba neteisingos rakto konfigūracijos.

„Supabase“ disko konfigūracijos faile `config/filesystems.php` konfigūracija nurodo lauke `key` naudoti „privilegijuotą raktą“ , aiškiai nurodant, kad tik skaitymui skirtas raktas neveiks. Tai reiškia, kad reikia naudoti paslaugos raktą su rašymo teisėmis į saugyklą, o ne tiesiog kliento pusės viešąjį API raktą arba S3 suderinamumo raktą be modifikavimo teisių.

„Supabase“ skydelyje, API ir saugyklos konfigūracijos skyriuje, rasite ir anoniminius raktus, ir „service_role“ raktus (arba jų atitikmenis) , kurie turi išplėstines teises. Būtent šį paslaugos raktą, o ne viešąjį, turėtumėte įdėti į kintamąjį „SUPABASE_SECRET_ACCESS_KEY“, kurį tvarkyklė nuskaitys naudodama env('SUPABASE_SECRET_ACCESS_KEY').

Jei testavote naudodami S3 raktą iš saugyklos konfigūracijos arba su projekto bendraisiais API raktais, labai tikėtina, kad šie kredencialai neturi rašymo teisių į konkretų segmentą, todėl įvyko rašymo klaida. Paprastai problemą išsprendžia rakto reikšmės pakeitimas į galiojantį paslaugos raktą su rašymo teisėmis ir patvirtinimas, kad segmentas egzistuoja ir yra teisingai pavadintas.

Be slaptažodžio, svarbu patikrinti, ar SUPABASE_STORAGE_BUCKET apibrėžtas saugyklos konteineris tiksliai atitinka „Supabase“ sąsajoje sukurtą saugyklos konteinerį, atsižvelgiant į didžiąsias ir mažąsias raides, ir ar galinis taškas atitinka teisingą to saugojimo egzemplioriaus URL. Tokia detalė kaip papildomas simbolis ar neteisingas domenas gali neleisti adapteriui rasti tikrosios failų paskirties vietos.

Darbo eiga su „Laravel Breeze“, „Blade“ ir „Supabase Storage“

Sukonfigūravus duomenų bazę ir saugyklą, kitas logiškas žingsnis – viską integruoti su „Laravel Breeze“ sąsaja ir „Blade“ šablonais . Tokiu būdu vartotojai gali registruotis, autentifikuotis ir įkelti failus į „Supabase“ neišeidami iš „Laravel“ ekosistemos.

Valdikliuose naudotumėte saugyklos fasadą , nukreipiantį į „supabase“ diską. Pavyzdžiui, norėdami įkelti iš formos gautą failą su failo įvestimi, galite atlikti tokius veiksmus:

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

Šis kodas nurodo „Laravel“ naudoti „Supabase“ diską ir įkelti failą į virtualų įkėlimų aplanką sukonfigūruotame saugyklos skyriuje. Jei raktas ir galinis taškas yra teisingi, failas bus įkeltas į „Supabase“ saugyklą, o jūs galėsite gauti jo kelią arba sugeneruoti viešus arba pasirašytus URL adresus naudodami standartinius saugojimo metodus.

Šio metodo privalumas yra tas, kad jūsų programa palaiko vieną saugojimo sąsają, nepriklausomai nuo to, ar ji naudoja vietinį diską, „Amazon S3“, „Supabase“ ar kitą palaikomą paslaugą. Tiekėjų keitimas apsiriboja config/filesystems.php ir aplinkos kintamųjų koregavimu, nepaveikiant verslo logikos.

Derindami tai su „Blade“ ir „Breeze“, galite pasiūlyti įkėlimo formas, failų sąrašus ir atsisiuntimo nuorodas, visiškai integruotas į jūsų programos naudotojo patirtį. Be to, „Supabase Storage“ duomenų rinkiniais ir politika pagrįstas metodas leidžia panaudoti prieigos kontrolę ir saugumo taisykles, kad apibrėžtumėte, ką kiekvienas naudotojas gali peržiūrėti arba atsisiųsti.

Visa ši paketų, tvarkyklių ir konfigūracijų ekosistema leidžia „Laravel“ sklandžiai dirbti su „Supabase“ tiek reliacinių duomenų su „Postgres“, tiek failų saugojimo ir UUID valdymo srityse . Tinkamai sukonfigūravę raktus, schemas ir tvarkykles, pasieksite labai tvirtą integraciją, kuri padės išvengti daugelio tipinių klaidų, su kuriomis susiduriama bandant rankiniu būdu sujungti abi platformas be šių palaikymo sluoksnių.

„Laravel“ sujungimas su „Supabase“ duomenų bazei ir saugyklai, specialios „Supabase“ tvarkyklės panaudojimas UUID valdymui be galvos skausmo ir „Flysystem“ adapterio naudojimas saugyklai leidžia kurti modernias programas, kuriose visa sudėtinga infrastruktūra yra integruota į švarią „Laravel“ API sąsają – nuo ​​perkėlimų ir autentifikavimo iki failų įkėlimo į saugius saugyklų segmentus.