Kuidas integreerida Supabase Laraveliga andmebaasi ja salvestusruumi jaoks?

Informatec Digital » Ressursid » Kuidas integreerida Supabase Laraveliga andmebaasi ja salvestusruumi jaoks?

Kui töötad Laraveliga ja oled pühendunud backend-programmeerimisele ning soovid üle minna kaasaegsele ja hallatud PostgreSQL-i andmebaasile nagu Supabase , oled ilmselt aru saanud, et ainult paari muutuja muutmisest .env-failis ei piisa. On olemas ühenduse üksikasjad, skeemid, autentimine ja failide salvestusruum, mille tähelepanuta jätmine võib põhjustada üsna krüptilisi vigu.

Lisaks, kui soovite minna sammu edasi ja kasutada Supabase'i failisalvestusena, mis on integreeritud Laraveli kettasüsteemiga (Storage), muutuvad asjad veidi keerulisemaks: teenusevõtmed, ämbrid, lõpp-punktid, kohandatud Flysystemi draiverid jne. Hea uudis on see, et kõike saab üsna puhtalt integreerida – andmebaasi, salvestusruumi ja UUID-de haldamist.

Laraveli ühendamine Supabase'i andmebaasiga

Esimene samm on toimiva Laraveli projekti loomine ja selle linkimine Supabase'i pakutava Postgresi andmebaasiga. Selleks vajate keskkonda, kus on ajakohane PHP ja Composer , ning saate luua uue projekti või kasutada olemasolevat. Konsoolis genereerige lihtsalt projekt standardse Laraveli käsu abil ja seejärel alustage ühenduse seadistamist.

Kui projekti raamistik on paigas, on tavapraktikaks paigaldada lihtne autentimissüsteem. Laravel Breeze sobib siia väga hästi, kuna see sisaldab Blade'i malle ja lihtsat sisselogimis- ja registreerimisvoogu , mis võimaldab teil kiiresti kontrollida, kas teie andmebaasiühendus on õigesti konfigureeritud ja kas saate kasutajaid probleemideta luua.

Ühenduse üksikasjade saamiseks logige sisse oma Supabase'i armatuurlauale ja looge uus andmebaasiprojekt (seda saate teha otse failist `database.new` , mis suunab teid viisardisse). Kui teil veel kontot pole, näete kõigepealt registreerimisekraani; kui teil see juba on, lähete otse projekti seadetesse ja jaotisse, kust leiate ühendusstringi.

Projekti lehel leiate ühenduste jaotisest nupu „Ühenda” või midagi sarnast. Sellele klõpsates kuvatakse mitu ühendusstringi vormingut (URI, üksikud parameetrid jne). Kopeerige kogu URI, kuid pidage meeles, et asendage parool andmebaasi jaoks tegelikult kasutatava parooliga, kuna sageli kuvatakse vaikeparool või kohatäide.

Selle teabe abil peate minema oma Laraveli projekti .env-faili ja värskendama muutujaid DB_HOST, DB_PORT, DB_DATABASE, DB_USERNAME ja DB_PASSWORD või konfigureerima muutuja DATABASE_URL, kui eelistate kasutada täisstringi vormingut. Eesmärk on tagada, et kõik osutaks Supabase Postgres klastrile , mitte teie localhostile.

Postgresi draiveri ja Supabase'i skeemi seadistamine Laravelis

Laravelis on andmebaasi konfigureerimise võtmefail config/database.php . Kuigi raamistikuga kaasasolevat pgsql-draiverit saab otse kasutada, on Supabase'iga töötades tavaline rakendada mõningaid lisaseadeid, eriti skeemide ja Postgres-spetsiifiliste valikute osas.

Tüüpiline Postgresi konfiguratsioon Laravelis võib ühenduste massiivis võtme 'pgsql' all välja näha selline :

'pgsql' => ,

Võti peitub siin parameetris `search_path` . Supabase kasutab vaikimisi `public` skeemi, mis on see, mis on nähtav tema API-de kaudu. Kui soovite oma Laraveli rakenduse sellest skeemist eraldi hoida ja vältida tabelite või poliitikate konflikte, on tungivalt soovitatav muuta `search_path` oma skeemiks, näiteks `laravel` , nagu eelmises näites näha.

Sel viisil luuakse teie projekti loodud migratsioonid ja tabelid selles alternatiivses skeemis, mitte avalikult. See eraldamine lihtsustab oluliselt turvareeglite, RLS-i ja Supabase paneeli kaudu juurdepääsu haldamist ilma midagi üle kirjutamata, hoides samal ajal andmebaasi struktuuri korrastatuna.

Kui olete konfiguratsioonifaili kohandanud, saate migratsioone käivitada standardsete Laraveli käskudega. See loob autentimistabelid ja kõik muud teie määratletud tabelid. Kui kõik on õigesti konfigureeritud, käivituvad käsud Supabase Postgres serveris automaatselt.

Kui migreerimine on lõppenud, käivitage arendusserver käsuga `artisan serve` ja proovige kasutajaid registreerida ja sisse logida. Kui ühenduse ega migreerimise vigu ei ilmne, tähendab see, et Laravel suhtleb Supabase'iga õigesti ja saate oma äriloogika loomist tavapäraselt jätkata.

Spetsiifilise Supabase'i draiveri kasutamine Laravelis

Kuigi standardne pgsql-draiver töötab, on olemas pakett, mis lisab Laraveli jaoks supabase'i andmebaasidraiveri , laiendades PostgreSQL-i käitumist väga kasulike täiustustega, eriti UUID-veergude käsitlemise ja päringute koostamise viisi osas.

See pakett, mida levitatakse nime all prahsys/laravel-supabase, installitakse Composeri kaudu ja see registreerib täiendava draiveri nimega supabase, mida saate kasutada oma config/database.php failis. Sisemiselt põhineb see Laraveli Postgresi draiveril, kuid sisaldab sätteid ja päringugrammatikaid, mis on optimeeritud konkreetse Supabase'i keskkonna jaoks.

Pärast installimist võiksite ühenduste jaotises deklareerida midagi sellist :

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

Selle draiveri eeliseks on see, et saate endiselt Postgresi mootori täisvõimsuse, kuid see käsitleb automaatselt ka teatud tundlikke Supabase'i üksikasju, eriti UUID-dega primaarvõtmete või seoseväljadena töötamisel . See väldib vajadust käsitsi kirjutada ülekandeid igas keerulises päringus.

Pakett on loodud sobima hästi ka raamistiku ja PHP tänapäevaste versioonidega, pakkudes ametlikku ühilduvust Laravel 10.x, 11.x ja 12.x ning PHP-ga alates versioonist 8.1, samuti mis tahes standardse PostgreSQL-i andmebaasiga, sealhulgas muidugi Supabase'iga.

Kõikide korrektseks toimimiseks sisaldab pakett automatiseeritud testide komplekti. Teste saab käivitada käsuga `composer test`, mis kasutab kiiruse huvides mälus olevat SQLite andmebaasi, või valmistada ette `.env.testing` fail, mis osutab teie Supabase'ile, ja käivitada käsu `composer test-supabase`, et kontrollida selle toimimist reaalses keskkonnas kaug-Postgresiga.

UUID-de haldamine Supabase'is ja Laravelis

Supabase'il on UUID-veergudega üks eripära: kui proovite UUID-d otse tekstistringiga võrrelda ilma teisenduseta, võib päring nurjuda või tagastada ootamatuid tulemusi . Paljas Postgresi keskkonnas saaks selle lahendada globaalsete teisenduste või kohandatud operaatoritega, kuid Supabase selliseid globaalseid kohandusi ei luba.

See tähendab , et stiili otsene päring:

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

See ei tööta nii , nagu võiks arvata. Kui aga teed selgesõnalise valiku:

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

Päring õnnestus. Probleem on selles, et Laravelis ei taha Eloquenti või päringukoostajaga päringuid kirjutades igale WHERE-klauslile CAST-e lisada . Siin tulebki mängu eelmainitud paketi supabase draiver, mis lisab need teisendused sinu eest.

Kui see draiver on aktiivne, saate teha tavalisi päringuid , näiteks:

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

Ja mitte ainult otsepäringutes, vaid ka liitumistes . Näiteks kui soovite postitusi hankida ja need UUID-välja abil kasutajate tabeliga ühendada, võiksite teha midagi sellist:

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

Draiver rakendab vajalikke teksti teisendusi asjakohastele UUID veergudele läbipaistvalt. Nii jääb teie kood Laraveli jaoks idioomaatiliseks ja te ei pea kirjutama toorest SQL-i ega kasutama igas keerulises päringus imelikke nippe.

Kui soovite täpsemat kontrolli selle üle, milliseid veerge UUID-dena käsitletakse, pakub pakett teie Eloquent mudelite jaoks CastsUuidColumns omadust . Kasutage seda lihtsalt oma mudeliklassis ja defineerige kaitstud massiiv lisaveergudest:

use Prahsys\Supabase\Traits\CastsUuidColumns;

class Post extends Model
{
    use CastsUuidColumns;

    protected $uuidColumns = ;
}

See omadus teeb kolme olulist asja: see lisab primaarvõtme vaikimisi UUID-na, lisab kõik teie deklareeritud veerud atribuudile `$uuidColumns` ja edastab selle teabe päringu koostajale, et see teaks, kuhu teisendusi rakendada. See muudab kogu UUID-dega seotud andmetele juurdepääsu ühtseks ja automatiseeritud.

Veelgi keerukamate juhtumite korral saate registreerida kohandatud UUID-veerudetektori. Paketi PostgresGrammari abil saate määrata tagasihelistusfunktsiooni, mis veeru nime või päringu konteksti põhjal otsustab, kas seda tuleks käsitleda UUID-na. Näiteks:

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

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

Selle funktsiooni seadistamise korral saab süsteem UUID-dena käsitleda kõiki veerge, mille nimel on teatud muster või mis asuvad kindlas loendis, kohandudes teie projekti väga spetsiifiliste nimetamiskonventsioonidega .

Integreeri Supabase Storage failisüsteemina Laraveli

Lisaks andmebaasile peavad paljud projektid salvestama pilte, dokumente või muid kasutajate üleslaaditud faile. Supabase sisaldab ämbripõhist salvestusteenust, mida saab Flysystemi kaudu kasutada Laraveli kettana . Saadaval on spetsiaalne adapter, mis käsitleb Supabase Storage'i täiendava draiverina config/filesystems.php sees.

Kõnealune pakett pakub Flysystemi adapterit, mis integreerub sujuvalt raamistiku salvestussüsteemiga. See vastab PHP >= 8.1, Laravel 10.x ja 11.x miinimumnõuetele ning PHP fileinfo laiendile (ext-fileinfo), mida Laravel tavaliselt failide haldamiseks soovitab. Installimine toimub Composeri abil ja kui see on kaasatud, peate konfiguratsioonis määratlema vaid supabase ketta.

Faili config/filesystems.php ketaste massiivi sisse tuleks lisada midagi sarnast järgmisega:

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

Parameeter `bucket` on tavaliselt lihtsalt Supabase'i armatuurlaual loodud salvestusämbri nimi (näiteks `myapp-file-uploads`). Parameeter `endpoint` on projekti salvestusteenuse baas-URL, mis on nähtav ka armatuurlaua vastavas osas ja mis tuletatakse tavaliselt projekti URL-ist ja piirkonnast.

Valik „public” näitab, kas ämbri sisu käsitletakse vaikimisi avalikuna. Kui see on „true”, genereerib adapter ligipääsetavad URL-id ilma spetsiaalse allkirjata; kui see on „false”, siis tuleb mängu valik „defaultUrlGeneration”, mis võib sundida allkirjastatud URL-ide genereerimist aegumisajaga, mis on määratud valikuga „signedUrlExpires”. See konfiguratsioon võimaldab teil tasakaalustada turvalisust ja mugavust olenevalt käsitletavate failide tüübist.

Üldine ketta URL jäetakse tavaliselt tühjaks, nii et adapter tuletab selle automaatselt lõpp-punktist. Seda tuleks muuta ainult siis, kui kasutate vahendavat puhverserverit või CDN-i ja soovite, et genereeritud marsruudid osutaksid sellele domeenile, mitte Supabase'i natiivsele domeenile.

Üleslaadimisvigade tõrkeotsing ja Supabase Storage'i toimimise põhimõtete mõistmine

Laravelist failide Supabase Storage'i üleslaadimisel on üsna levinud probleem selliste teadete saamine nagu „Faili ei saa kirjutada asukohta: üleslaadimised/…“ . See näitab tavaliselt, et kuigi draiver on konfigureeritud, keelab Supabase kirjutamistoimingu ebapiisavate õiguste või vale võtme konfiguratsiooni tõttu.

Supabase'i ketta konfiguratsioonifailis `config/filesystems.php` määrab konfiguratsioon väljal `key` ära "privilegeeritud võtme" , mis ütleb selgesõnaliselt, et kirjutuskaitstud võti ei tööta. See tähendab, et peate kasutama ämbri kirjutamisõigustega teenusevõtit, mitte lihtsalt kliendipoolset avalikku API-võtit või muutmisõigusteta S3-ühilduvusvõtit.

Supabase'i paneelil API ja salvestusruumi konfiguratsiooni jaotises leiate nii anonüümsed võtmed kui ka service_role võtmed (või nende ekvivalendid) , millel on laiendatud õigused. Just see teenindusvõti, mitte avalik võti, tuleks paigutada muutujasse SUPABASE_SECRET_ACCESS_KEY, mille draiver seejärel env('SUPABASE_SECRET_ACCESS_KEY') abil loeb.

Kui olete testinud salvestuskonfiguratsioonist pärit S3-võtmega või projekti üldiste API-võtmetega, on väga tõenäoline, et neil volitustel pole konkreetsele ämbrile kirjutamisõigusi, mis põhjustab kirjutamisvea. Tavaliselt lahendab probleemi võtme väärtuse muutmine kehtivaks kirjutamisõigustega teenusevõtmeks ja ämbri olemasolu ning õige nimega kontrollimine.

Lisaks paroolile on oluline kontrollida, et SUPABASE_STORAGE_BUCKET-is määratletud ämber vastab täpselt Supabase'i liideses loodule, austades suur- ja väiketähti, ning et lõpp-punkt vastab selle salvestusinstantsi õigele URL-ile. Üksikasjad, näiteks lisamärk või vale domeen, võivad takistada adapteril failide tegeliku sihtkoha leidmist.

Töövoog Laravel Breeze'i, Blade'i ja Supabase Storage'iga

Kui andmebaas ja salvestusruum on konfigureeritud, on järgmine loogiline samm integreerida kõik Laravel Breeze'i liidese ja Blade'i mallidega . Nii saavad kasutajad registreeruda, autentida ja faile Supabase'i üles laadida Laraveli ökosüsteemist lahkumata.

Kontrollerites kasutaksite salvestusfassaadi , mis osutab supabase-kettale. Näiteks vormilt saadud faili üleslaadimiseks koos faili sisendiga võiksite teha midagi sellist:

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

See kood käsib Laravelil kasutada Supabase'i ketast ja paigutada fail konfigureeritud ämbri virtuaalsesse üleslaadimiste kausta. Kui võti ja lõpp-punkt on õiged, laaditakse fail üles Supabase'i salvestusruumi ja saate selle tee hankida või genereerida avalikke või allkirjastatud URL-e standardsete salvestusmeetodite abil.

Selle lähenemisviisi eeliseks on see, et teie rakendusel on salvestuseks üks liides, olenemata sellest, kas see kasutab kohalikku ketast, Amazon S3-d, Supabase'i või muud toetatud teenust. Pakkujate vahetamine piirdub config/filesystems.php ja keskkonnamuutujate kohandamisega, ilma et see mõjutaks äriloogikat.

Kombineerides seda Blade'i ja Breeze'iga, saate pakkuda üleslaadimisvorme, faililoendeid ja allalaadimislinke, mis on täielikult integreeritud teie rakenduse kasutuskogemusse. Lisaks võimaldab Supabase Storage'i ämbri- ja poliitikapõhine lähenemisviis teil kasutada selle juurdepääsukontrolle ja turvareegleid, et määratleda, mida iga kasutaja saab vaadata või alla laadida.

See pakettide, draiverite ja konfiguratsioonide ökosüsteem võimaldab Laravelil sujuvalt Supabase'iga töötada nii Postgresi relatsioonandmete kui ka failide salvestamise ja UUID-de haldamise osas . Võtmete, skeemide ja draiverite õige konfigureerimisega saavutate väga tugeva integratsiooni, mis väldib paljusid tüüpilisi vigu, mis tekivad mõlema platvormi käsitsi ühendamisel ilma nende toetavate kihtideta.

Laraveli ühendamine Supabase'iga andmebaasi ja salvestusruumi jaoks, spetsiaalse Supabase'i draiveri kasutamine UUID-de haldamiseks ilma peavaludeta ja Flysystemi adapteri kasutamine salvestusruumi jaoks võimaldab teil luua kaasaegseid rakendusi, kus kogu keeruline infrastruktuur on kapseldatud Laraveli puhta API taha, alates migratsioonidest ja autentimisest kuni failide üleslaadimiseni turvalistesse ämbritesse.