Si të integrohet Supabase me Laravel për bazën e të dhënave dhe ruajtjen

Informatec Digital » Burime » Si të integrohet Supabase me Laravel për bazën e të dhënave dhe ruajtjen

Nëse punoni me Laravel dhe jeni të përkushtuar ndaj programimit backend , dhe po kërkoni të bëni kalimin në një bazë të dhënash moderne dhe të menaxhuar PostgreSQL si Supabase , ndoshta e keni kuptuar se ndryshimi i vetëm i disa variablave në skedarin .env nuk është i mjaftueshëm. Ka detaje lidhjeje, skema, autentifikim dhe ruajtje skedarësh që, nëse lihen pas dore, mund të çojnë në disa gabime mjaft të fshehta.

Për më tepër, kur doni të shkoni një hap më tej dhe të përdorni Supabase si hapësirë ​​ruajtjeje skedarësh të integruar me sistemin e diskut të Laravel (Storage), gjërat bëhen pak më të komplikuara: çelësat e shërbimit, bucket-et, pikat fundore, drajverët e personalizuar të Flysystem, etj. Lajmi i mirë është se gjithçka mund të integrohet në mënyrë të përsosur - baza e të dhënave, hapësira e ruajtjes dhe trajtimi i UUID - në një mënyrë mjaft të pastër.

Lidhja e Laravel me bazën e të dhënave Supabase

Hapi i parë është të keni një projekt Laravel funksional dhe ta lidhni atë me bazën e të dhënave Postgres të ofruar nga Supabase. Për këtë, ju nevojitet një mjedis me PHP dhe Composer të përditësuar , dhe mund të krijoni një projekt të ri ose të përdorni një ekzistues. Nga konzola, thjesht gjeneroni projektin duke përdorur komandën standarde Laravel dhe më pas filloni të konfiguroni lidhjen.

Pasi të keni vendosur kornizën e projektit, praktika e zakonshme është të instaloni një sistem të thjeshtë vërtetimi. Laravel Breeze përshtatet shumë mirë sepse përfshin shabllone Blade dhe një rrjedhë bazë hyrjeje dhe regjistrimi , duke ju lejuar të vërtetoni shpejt që lidhja juaj me bazën e të dhënave është konfiguruar siç duhet dhe që mund të krijoni përdorues pa probleme.

Për të marrë detajet e lidhjes, hyni në panelin tuaj të Supabase dhe krijoni një projekt të ri të bazës së të dhënave (mund ta bëni këtë direkt nga `database.new` , i cili të ridrejton te asistenti). Nëse nuk keni ende një llogari, së pari do të shihni ekranin e regjistrimit; nëse tashmë keni një, do të shkoni direkt te cilësimet e projektit dhe seksioni ku mund të gjeni vargun e lidhjes.

Brenda faqes së projektit, në seksionin e lidhjes, do të gjeni një buton "Lidhu" ose diçka të ngjashme. Klikimi i tij do të shfaqë disa formate të vargut të lidhjes (URI, parametra individualë, etj.). Kopjoni URI-n e plotë, por mos harroni të zëvendësoni fjalëkalimin me atë që përdorni në të vërtetë për bazën e të dhënave, pasi shpesh shfaqet një fjalëkalim ose vendmbajtës i parazgjedhur.

Me këtë informacion, duhet të shkoni te skedari .env i projektit tuaj Laravel dhe të përditësoni variablat DB_HOST, DB_PORT, DB_DATABASE, DB_USERNAME dhe DB_PASSWORD, ose të konfiguroni variablin DATABASE_URL nëse preferoni të përdorni formatin e plotë të vargut. Qëllimi është të siguroheni që gjithçka të tregojë te klasteri Supabase Postgres dhe jo te localhost-i juaj.

Konfiguroni drajverin Postgres dhe skemën Supabase në Laravel

Në Laravel, skedari kyç për konfigurimin e bazës së të dhënave është config/database.php . Edhe pse mund ta përdorni direkt drajverin pgsql që vjen me kornizën, kur punoni me Supabase është e zakonshme të aplikoni disa cilësime shtesë, veçanërisht në lidhje me skemat dhe opsionet specifike të Postgres.

Një konfigurim tipik i Postgres në Laravel mund të duket kështu, brenda grupit të lidhjeve, nën çelësin 'pgsql' :

'pgsql' => ,

Çelësi këtu qëndron te parametri `search_path` . Supabase, si parazgjedhje, përdor skemën `public`, e cila është ajo që ekspozohet përmes API-ve të saj. Nëse doni ta mbani aplikacionin tuaj Laravel të ndarë nga ajo skemë dhe të shmangni konfliktet e tabelave ose politikave, rekomandohet fuqimisht të ndryshoni `search_path` në skemën tuaj, për shembull, `laravel` , siç shihet në shembullin e mëparshëm.

Në këtë mënyrë, migrimet dhe tabelat e gjeneruara nga projekti juaj do të krijohen në këtë skemë alternative dhe jo në publik. Kjo ndarje thjeshton shumë menaxhimin e rregullave të sigurisë, RLS dhe aksesit nga paneli Supabase pa mbishkruar asgjë që nuk duhet, duke e mbajtur strukturën e bazës së të dhënave të organizuar.

Pasi ta keni rregulluar skedarin e konfigurimit, mund të ekzekutoni migrimet duke përdorur komandat standarde të Laravel. Kjo do të krijojë tabelat e vërtetimit dhe çdo tabelë tjetër që keni përcaktuar. Nëse gjithçka është konfiguruar saktë, komandat do të ekzekutohen automatikisht në serverin Supabase Postgres.

Pasi të përfundojnë migrimet, nisni serverin e zhvillimit me `artisan serve` dhe provoni të regjistroni dhe identifikoni përdoruesit. Nëse nuk shfaqen gabime lidhjeje ose migrimi, kjo do të thotë që Laravel po komunikon saktë me Supabase dhe ju mund të vazhdoni të ndërtoni logjikën tuaj të biznesit si zakonisht.

Duke përdorur një drajver specifik Supabase në Laravel

Edhe pse drajveri standard pgsql funksionon, ekziston një paketë që shton një drajver të bazës së të dhënave supabase për Laravel , duke zgjeruar sjelljen e PostgreSQL me përmirësime shumë të dobishme, veçanërisht në lidhje me trajtimin e kolonave UUID dhe mënyrën se si ndërtohen pyetjet.

Ky paketë, i shpërndarë si prahsys/laravel-supabase, instalohet nëpërmjet Composer dhe regjistron një drajver shtesë të quajtur supabase që mund ta përdorni në skedarin tuaj config/database.php. Brenda, bazohet në drajverin Postgres të Laravel, por përfshin cilësime dhe gramatika pyetjesh të optimizuara për mjedisin specifik Supabase.

Pasi të instalohet, mund të deklaroni diçka si më poshtë brenda seksionit të lidhjeve :

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

Avantazhi i përdorimit të këtij drajveri është se ju ende merrni fuqinë e plotë të motorit Postgres, por ai gjithashtu trajton automatikisht disa detaje delikate të Supabase, veçanërisht kur punoni me UUID si çelësa primarë ose fusha marrëdhëniesh . Kjo shmang nevojën për të shkruar manualisht transmetimin në çdo pyetje komplekse.

Paketa është projektuar gjithashtu për t'u përshtatur mirë me versionet moderne të framework-ut dhe PHP-së, duke ofruar përputhshmëri zyrtare me Laravel 10.x, 11.x dhe 12.x dhe me PHP nga versioni 8.1 e tutje, si dhe me çdo bazë të dhënash standarde PostgreSQL, duke përfshirë sigurisht Supabase.

Për t'u siguruar që gjithçka funksionon siç duhet, paketa përfshin një sërë testesh të automatizuara. Mund t'i ekzekutoni testet me komandën `composer test`, e cila do të përdorë një bazë të dhënash SQLite në memorie për shpejtësi, ose të përgatitni një skedar `.env.testing` që tregon Supabase-in tuaj dhe të ekzekutoni `composer test-supabase` për të verifikuar sjelljen në një mjedis të botës reale me Postgres të largët.

Menaxhimi i UUID në Supabase dhe Laravel

Supabase ka një veçori me kolonat UUID: nëse përpiqeni të krahasoni një UUID direkt me një varg teksti pa përdorur metodën e transmetimit (casting), pyetja mund të dështojë ose të kthejë rezultate të papritura . Në një mjedis të thjeshtë Postgres, mund ta zgjidhni këtë me anë të transmetimeve globale ose operatorëve të personalizuar, por Supabase nuk lejon personalizime të tilla globale.

Kjo nënkupton që një pyetje e drejtpërdrejtë e stilit:

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

Nuk do të funksionojë siç mund ta prisni. Megjithatë, nëse bëni përzgjedhjen e aktorëve të saktë:

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

Pyetja është përfunduar me sukses. Problemi është se në Laravel, kur shkruani pyetje me Eloquent ose me ndërtuesin e pyetjeve, nuk doni të shtoni CAST në çdo klauzolë WHERE . Këtu hyn në lojë drajveri supabase nga paketa e lartpërmendur, i cili shton këto cast-e për ju.

Me atë drajver aktiv, mund të kryeni pyetje të zakonshme si:

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

Dhe jo vetëm në pyetjet direkte, por edhe në bashkime . Për shembull, nëse doni të merrni postime dhe t'i bashkoni ato me tabelën e përdoruesve duke përdorur një fushë UUID, mund të bëni diçka të tillë:

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

Drajveri trajton zbatimin e transkriptimeve të nevojshme të tekstit në kolonat përkatëse UUID në mënyrë transparente. Në këtë mënyrë, kodi juaj mbetet idiomatik për Laravel dhe nuk keni nevojë të shkruani SQL të papërpunuar ose të përdorni truke të çuditshme në çdo pyetje komplekse.

Nëse dëshironi një kontroll më të hollësishëm mbi kolonat që konsiderohen UUID, paketa ofron tiparin CastsUuidColumns për modelet tuaja Eloquent. Thjesht përdoreni atë në klasën tuaj të modelit dhe përcaktoni një grup të mbrojtur kolonash shtesë:

use Prahsys\Supabase\Traits\CastsUuidColumns;

class Post extends Model
{
    use CastsUuidColumns;

    protected $uuidColumns = ;
}

Kjo veçori bën tre gjëra të rëndësishme: përfshin çelësin primar si UUID-in e parazgjedhur, shton çdo kolonë që deklaroni në pronën `$uuidColumns` dhe ia komunikon këtë informacion ndërtuesit të pyetjeve në mënyrë që ai të dijë se ku t'i aplikojë konvertimet. Kjo e bën të gjithë aksesin në të dhëna që përfshin UUID-të të qëndrueshëm dhe të automatizuar.

Për raste edhe më të avancuara , mund të regjistroni një detektor kolonash UUID të personalizuar. Duke përdorur PostgresGrammar nga paketa, mund të specifikoni një funksion rikthimi që, bazuar në emrin e kolonës ose kontekstin e pyetjes, vendos nëse duhet të trajtohet si UUID. Për shembull:

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

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

Me konfigurimin e këtij funksioni, sistemi mund të konsiderojë si UUID të gjitha kolonat, emri i të cilave ka një model të caktuar ose është brenda një liste specifike, duke u përshtatur me konventat shumë specifike të emërtimit të projektit tuaj.

Integroni Supabase Storage si një sistem skedarësh në Laravel

Përveç bazës së të dhënave, shumë projekte duhet të ruajnë imazhe, dokumente ose skedarë të tjerë të ngarkuar nga përdoruesit. Supabase përfshin një shërbim ruajtjeje të bazuar në kova që mund ta përdorni si disk të Laravel nëpërmjet Flysystem . Një përshtatës specifik është i disponueshëm për të trajtuar Supabase Storage si një drajver shtesë brenda config/filesystems.php.

Paketa në fjalë ofron një përshtatës Flysystem që integrohet pa probleme me sistemin e ruajtjes së framework-ut. Ai përmbush kërkesat minimale të PHP >= 8.1, Laravel 10.x dhe 11.x , dhe zgjerimin PHP fileinfo (ext-fileinfo), të cilin Laravel zakonisht e rekomandon për trajtimin e skedarëve. Instalimi bëhet duke përdorur Composer, dhe pasi të përfshihet, ju vetëm duhet të përcaktoni diskun supabase në konfigurim.

Në skedarin config/filesystems.php , brenda vargut disk, do të shtonit diçka të ngjashme me sa vijon:

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

Parametri `bucket` zakonisht është thjesht emri i kovës së ruajtjes që keni krijuar në panelin e kontrollit të Supabase (për shembull, `myapp-file-uploads`). `endpoint` është URL-ja bazë e shërbimit të ruajtjes së projektit, e dukshme edhe në seksionin përkatës të panelit të kontrollit dhe zakonisht rrjedh nga URL-ja dhe rajoni i projektit.

Opsioni `public` tregon nëse përmbajtja e kovës do të trajtohet si publike si parazgjedhje. Nëse `true`, përshtatësi do të gjenerojë URL të aksesueshme pa një nënshkrim të veçantë; nëse `false`, hyn në lojë opsioni `defaultUrlGeneration`, i cili mund të detyrojë gjenerimin e URL-ve të nënshkruara me një kohë skadimi të specifikuar nga `signedUrlExpires`. Ky konfigurim ju lejon të balanconi sigurinë dhe komoditetin në varësi të llojit të skedarëve që trajtoni.

URL-ja e përgjithshme e diskut normalisht lihet si null në mënyrë që përshtatësi ta nxjerrë automatikisht atë nga pika fundore. Duhet ta modifikoni vetëm nëse po përdorni një ndërmjetës proxy ose CDN dhe dëshironi që rrugët e gjeneruara të tregojnë në atë domen në vend të domenit vendas Supabase.

Zgjidh gabimet e ngarkimit dhe kuptoj çelësin e Supabase Storage

Një problem mjaft i zakonshëm kur përpiqeni të ngarkoni skedarë në Supabase Storage nga Laravel është marrja e mesazheve të tilla si "Nuk mund të shkruhet skedari në vendndodhjen: uploads/..." . Kjo zakonisht tregon se, megjithëse drajveri është konfiguruar, Supabase po e mohon operacionin e shkrimit për shkak të lejeve të pamjaftueshme ose një konfigurimi të gabuar të çelësit.

Në skedarin e konfigurimit të diskut supabase, `config/filesystems.php`, konfigurimi specifikon përdorimin e një "çelësi të privilegjuar" në fushën `çelës`, duke deklaruar në mënyrë të qartë se një çelës vetëm për lexim nuk do të funksionojë. Kjo do të thotë që duhet të përdorni një çelës shërbimi me leje shkrimi në bucket, jo thjesht një çelës publik API nga ana e klientit ose një çelës përputhshmërie S3 pa leje modifikimi.

Në panelin Supabase, brenda seksionit të konfigurimit të API-t dhe ruajtjes, do të gjeni çelësat anonimë dhe çelësat service_role (ose ekuivalentët e tyre) , të cilët kanë privilegje të zgjeruara. Është ky çelës shërbimi, jo ai publik, që duhet ta vendosni në variablin SUPABASE_SECRET_ACCESS_KEY, të cilin drajveri do ta lexojë më pas duke përdorur env('SUPABASE_SECRET_ACCESS_KEY').

Nëse keni qenë duke testuar me çelësin S3 nga konfigurimi i ruajtjes ose me çelësat gjenerikë API të projektit, ka shumë të ngjarë që ato kredenciale të mos kenë leje shkrimi në "kovën" specifike, duke rezultuar në gabimin e shkrimit. Ndryshimi i vlerës së çelësit në një çelës shërbimi të vlefshëm me leje shkrimi dhe konfirmimi që "kova" ekziston dhe është emërtuar saktë zakonisht e zgjidh problemin.

Përveç fjalëkalimit, është e rëndësishme të verifikohet që kova e përcaktuar në SUPABASE_STORAGE_BUCKET përputhet saktësisht me atë të krijuar në ndërfaqen Supabase, duke respektuar shkronjat e mëdha dhe të vogla, dhe që pika fundore korrespondon me URL-në e saktë për atë instancë ruajtjeje. Një detaj siç është një karakter shtesë ose një domen i pasaktë mund ta pengojë përshtatësin të gjejë destinacionin aktual të skedarëve.

Fluksi i punës me Laravel Breeze, Blade dhe Supabase Storage

Pasi të keni konfiguruar bazën e të dhënave dhe hapësirën e ruajtjes, hapi tjetër logjik është të integroni gjithçka me ndërfaqen Laravel Breeze dhe shabllonet Blade . Në këtë mënyrë, përdoruesit mund të regjistrohen, të autentifikojnë dhe të ngarkojnë skedarë në Supabase pa dalë nga ekosistemi Laravel.

Brenda kontrolluesve tuaj, do të përdorni fasadën e Storage që tregon diskun supabase. Për shembull, për të ngarkuar një skedar të marrë nga një formular me një input skedari, mund të bëni diçka të tillë:

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

Ky kod i tregon Laravel-it të përdorë diskun Supabase dhe ta vendosë skedarin brenda dosjes virtuale të ngarkimeve brenda kovës së konfiguruar. Nëse çelësi dhe pika fundore janë të sakta, skedari do të ngarkohet në hapësirën e ruajtjes Supabase dhe ju mund të merrni rrugën e tij ose të gjeneroni URL publike ose të nënshkruara duke përdorur metoda standarde të ruajtjes.

Avantazhi i kësaj qasjeje është se aplikacioni juaj mirëmban një ndërfaqe të vetme për ruajtje, pavarësisht nëse po përdor diskun lokal, Amazon S3, Supabase ose një shërbim tjetër të mbështetur. Ndërrimi i ofruesve reduktohet në rregullimin e variablave config/filesystems.php dhe mjedisit, pa ndikuar në logjikën e biznesit.

Duke e kombinuar këtë me Blade dhe Breeze, ju mund të ofroni formularë ngarkimi, lista skedarësh dhe lidhje shkarkimi të integruara plotësisht në përvojën e përdoruesit të aplikacionit tuaj. Për më tepër, qasja e bazuar në politika dhe në "kovë" e Supabase Storage ju lejon të shfrytëzoni kontrollet e aksesit dhe rregullat e sigurisë për të përcaktuar se çfarë mund të shikojë ose shkarkojë secili përdorues.

I gjithë ky ekosistem paketash, drajverësh dhe konfigurimesh i lejon Laravel të punojë pa probleme me Supabase, si në aspektin e të dhënave relacionale me Postgres ashtu edhe në ruajtjen e skedarëve dhe menaxhimin e UUID . Duke konfiguruar siç duhet çelësat, skemat dhe drajverët, ju arrini një integrim shumë të fuqishëm që shmang shumë nga gabimet tipike që hasen kur përpiqeni të lidhni të dy platformat manualisht pa këto shtresa mbështetëse.

Lidhja e Laravel me Supabase për bazën e të dhënave dhe ruajtjen, duke shfrytëzuar drajverin e dedikuar Supabase për të menaxhuar UUID-të pa dhimbje koke, dhe përdorimi i përshtatësit Flysystem për ruajtjen ju lejon të ndërtoni aplikacione moderne ku e gjithë infrastruktura komplekse është e kapsuluar pas API-t të pastër të Laravel, nga migrimet dhe autentifikimi deri te ngarkimi i skedarëve në "kofa" të sigurta.