Kā integrēt Supabase ar Laravel datubāzei un krātuvei

Informatec Digital » Resursi » Kā integrēt Supabase ar Laravel datubāzei un krātuvei

Ja strādājat ar Laravel un esat specializējies serveru programmēšanā , un vēlaties pāriet uz modernu, pārvaldītu PostgreSQL datubāzi, piemēram, Supabase , jūs droši vien esat sapratis, ka ar dažu mainīgo mainīšanu .env failā vien nepietiek. Ir savienojuma informācija, shēmas, autentifikācija un failu glabāšana, kas, ja netiek ņemtas vērā, var radīt diezgan neskaidras kļūdas.

Turklāt, ja vēlaties spert soli tālāk un izmantot Supabase kā failu glabātuvi, kas integrēta ar Laravel disku sistēmu (Storage), lietas kļūst nedaudz sarežģītākas: pakalpojumu atslēgas, segmenti, galapunkti, pielāgoti Flysystem draiveri utt. Labā ziņa ir tā, ka visu var pilnībā integrēt — datubāzi, krātuvi un UUID apstrādi — diezgan tīrā veidā.

Laravel savienošana ar Supabase datubāzi

Pirmais solis ir izveidot darbojošos Laravel projektu un saistīt to ar Supabase nodrošināto Postgres datubāzi. Šim nolūkam ir nepieciešama vide ar atjauninātu PHP un Composer , un jūs varat izveidot jaunu projektu vai izmantot esošu. No konsoles vienkārši ģenerējiet projektu, izmantojot standarta Laravel komandu, un pēc tam sāciet savienojuma iestatīšanu.

Kad projekta ietvars ir izveidots, parasti tiek instalēta vienkārša autentifikācijas sistēma. Laravel Breeze šeit ļoti labi iederas, jo tajā ir iekļautas Blade veidnes un pamata pieteikšanās un reģistrācijas plūsma , kas ļauj ātri pārbaudīt, vai jūsu datubāzes savienojums ir pareizi konfigurēts un vai varat bez problēmām izveidot lietotājus.

Lai iegūtu savienojuma informāciju, piesakieties savā Supabase informācijas panelī un izveidojiet jaunu datubāzes projektu (to var izdarīt tieši no `database.new` , kas novirza uz vedni). Ja jums vēl nav konta, vispirms redzēsiet reģistrācijas ekrānu; ja jums tāds jau ir, jūs nonāksiet tieši projekta iestatījumos un sadaļā, kur var atrast savienojuma virkni.

Projekta lapā, savienojuma sadaļā, atradīsiet pogu "Savienot" vai kaut ko līdzīgu. Noklikšķinot uz tās, tiks parādīti vairāki savienojuma virknes formāti (URI, atsevišķi parametri utt.). Nokopējiet pilnu URI, taču atcerieties aizstāt paroli ar to, ko faktiski izmantojat datubāzei, jo bieži tiek parādīta noklusējuma parole vai vietturis.

Ar šo informāciju jums jāatver sava Laravel projekta .env fails un jāatjaunina mainīgie DB_HOST, DB_PORT, DB_DATABASE, DB_USERNAME un DB_PASSWORD vai jākonfigurē mainīgais DATABASE_URL, ja vēlaties izmantot pilnu virknes formātu. Mērķis ir nodrošināt, lai viss norādītu uz Supabase Postgres klasteri , nevis uz jūsu lokālo serveri.

Konfigurējiet Postgres draiveri un Supabase shēmu Laravel vidē

Laravel vidē galvenais datubāzes konfigurēšanas fails ir config/database.php . Lai gan var tieši izmantot pgsql draiveri, kas nāk līdzi ietvaram, strādājot ar Supabase, ir ierasts lietot dažus papildu iestatījumus, īpaši attiecībā uz shēmām un Postgres specifiskajām opcijām.

Tipiska Postgres konfigurācija Laravel vidē varētu izskatīties šādi, savienojumu masīvā zem atslēgas 'pgsql' :

'pgsql' => ,

Šeit atslēga slēpjas parametrā `search_path` . Supabase pēc noklusējuma izmanto `publisko` shēmu, kas ir tā, kas ir pieejama, izmantojot tā API. Ja vēlaties, lai jūsu Laravel lietojumprogramma būtu atdalīta no šīs shēmas un izvairītos no tabulu vai politiku konfliktiem, ir ļoti ieteicams mainīt `search_path` uz savu shēmu, piemēram, `laravel` , kā redzams iepriekšējā piemērā.

Tādā veidā jūsu projekta ģenerētās migrācijas un tabulas tiks izveidotas šajā alternatīvajā shēmā, nevis publiski. Šī atdalīšana ievērojami vienkāršo drošības noteikumu, RLS un piekļuves pārvaldību no Supabase paneļa, nepārrakstot neko nevajadzīgu, vienlaikus saglabājot datubāzes struktūras kārtību.

Kad konfigurācijas fails ir pielāgots, migrācijas var palaist, izmantojot standarta Laravel komandas. Tas izveidos autentifikācijas tabulas un visas pārējās jūsu definētās tabulas. Ja viss ir pareizi konfigurēts, komandas automātiski darbosies Supabase Postgres serverī.

Kad migrācija ir pabeigta, startējiet izstrādes serveri ar `artisan serve` un mēģiniet reģistrēt un pieteikties lietotājiem. Ja neparādās savienojuma vai migrācijas kļūdas, tas nozīmē, ka Laravel pareizi sazinās ar Supabase un jūs varat turpināt veidot savu biznesa loģiku kā parasti.

Izmantojot īpašu Supabase draiveri Laravel vidē

Lai gan standarta pgsql draiveris darbojas, ir pieejama pakotne, kas pievieno supabase datubāzes draiveri Laravel , paplašinot PostgreSQL darbību ar ļoti noderīgiem uzlabojumiem, īpaši attiecībā uz UUID kolonnu apstrādi un vaicājumu konstruēšanas veidu.

Šī pakotne, kas izplatīta kā prahsys/laravel-supabase, tiek instalēta, izmantojot Composer, un reģistrē papildu draiveri ar nosaukumu supabase, ko varat izmantot savā config/database.php failā. Iekšēji tā ir balstīta uz Laravel Postgres draiveri, bet ietver iestatījumus un vaicājumu gramatiku, kas ir optimizēta konkrētajai Supabase videi.

Pēc instalēšanas savienojumu sadaļā varat deklarēt kaut ko līdzīgu šim :

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

Šī draivera izmantošanas priekšrocība ir tā, ka jūs joprojām iegūstat pilnu Postgres dzinēja jaudu, taču tas arī automātiski apstrādā noteiktus delikātus Supabase datus, īpaši strādājot ar UUID kā primārajām atslēgām vai relāciju laukiem . Tas ļauj izvairīties no nepieciešamības manuāli rakstīt pārveidošanu katrā sarežģītā vaicājumā.

Pakotne ir izstrādāta arī tā, lai tā labi iederētos modernajās ietvara un PHP versijās, piedāvājot oficiālu saderību ar Laravel 10.x, 11.x un 12.x un ar PHP, sākot no 8.1 versijas, kā arī ar jebkuru standarta PostgreSQL datubāzi, tostarp, protams, Supabase.

Lai nodrošinātu, ka viss darbojas pareizi, pakotnē ir iekļauts automatizētu testu komplekts. Testus var palaist ar komandu `composer test`, kas ātruma nodrošināšanai izmantos atmiņā esošu SQLite datubāzi, vai arī sagatavot failu `.env.testing`, kas norāda uz jūsu Supabase, un palaist komandu `composer test-supabase`, lai pārbaudītu darbību reālā vidē ar attālinātu Postgres.

UUID pārvaldība Supabase un Laravel

Supabase ir īpatnība ar UUID kolonnām: ja mēģināt salīdzināt UUID tieši ar teksta virkni bez pārveidošanas, vaicājums var neizdoties vai atgriezt negaidītus rezultātus . Nepilnīgā Postgres vidē to varētu atrisināt ar globāliem pārveidojumiem vai pielāgotiem operatoriem, taču Supabase neatļauj šādus globālus pielāgojumus.

Tas nozīmē , ka tiešs stila vaicājums:

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

Tas nedarbosies, kā varētu gaidīt. Tomēr, ja veiksiet tiešu atlasi:

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

Vaicājums ir veiksmīgs. Problēma ir tā, ka Laravel, rakstot vaicājumus ar Eloquent vai vaicājumu veidotāju, nav nepieciešams pievienot CAST katrai WHERE klauzulai . Šeit noder iepriekš minētās pakotnes supabase draiveris, kas pievieno šīs konversijas jūsu vietā.

Kad šis draiveris ir aktīvs, varat veikt bieži sastopamus vaicājumus , piemēram:

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

Un ne tikai tiešajos vaicājumos, bet arī apvienojumos . Piemēram, ja vēlaties izgūt ierakstus un apvienot tos ar lietotāju tabulu, izmantojot UUID lauku, varat rīkoties šādi:

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

Draiveris caurspīdīgi apstrādā nepieciešamo teksta pārveidojumu piemērošanu attiecīgajām UUID kolonnām. Tādā veidā jūsu kods Laravel valodā saglabājas idiomātisks, un jums nav jāraksta neapstrādāts SQL vai jāizmanto dīvaini triki katrā sarežģītā vaicājumā.

Ja vēlaties precīzāku kontroli pār to, kuras kolonnas tiek uzskatītas par UUID, pakotne piedāvā CastsUuidColumns funkciju jūsu Eloquent modeļiem. Vienkārši izmantojiet to savā modeļa klasē un definējiet aizsargātu papildu kolonnu masīvu:

use Prahsys\Supabase\Traits\CastsUuidColumns;

class Post extends Model
{
    use CastsUuidColumns;

    protected $uuidColumns = ;
}

Šī īpašība veic trīs svarīgas lietas: tā iekļauj primāro atslēgu kā noklusējuma UUID, pievieno visas jūsu deklarētās kolonnas `$uuidColumns` īpašībai un paziņo šo informāciju vaicājumu veidotājam, lai tas zinātu, kur lietot pārveidojumus. Tas padara visu datu piekļuvi, kas saistīta ar UUID, konsekventu un automatizētu.

Vēl sarežģītākos gadījumos varat reģistrēt pielāgotu UUID kolonnu detektoru. Izmantojot pakotnes PostgresGrammar, varat norādīt atzvanīšanas funkciju, kas, pamatojoties uz kolonnas nosaukumu vai vaicājuma kontekstu, izlemj, vai tā ir jāapstrādā kā UUID. Piemēram:

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

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

Iestatot šo funkciju, sistēma var uzskatīt par UUID visas kolonnas, kuru nosaukumam ir noteikts modelis vai kas atrodas noteiktā sarakstā, pielāgojoties ļoti specifiskām jūsu projekta nosaukumu piešķiršanas konvencijām .

Integrējiet Supabase Storage kā failu sistēmu Laravel vidē

Papildus datubāzei daudziem projektiem ir jāuzglabā attēli, dokumenti vai citi lietotāju augšupielādēti faili. Supabase ietver uz kausa balstītu krātuves pakalpojumu, ko var izmantot kā Laravel disku, izmantojot Flysystem . Ir pieejams īpašs adapteris, lai apstrādātu Supabase Storage kā papildu draiveri config/filesystems.php failā.

Attiecīgā pakotne nodrošina Flysystem adapteri, kas nemanāmi integrējas ar ietvara krātuves sistēmu. Tā atbilst PHP >= 8.1, Laravel 10.x un 11.x minimālajām prasībām , kā arī PHP fileinfo paplašinājumam (ext-fileinfo), ko Laravel parasti iesaka failu apstrādei. Instalēšana tiek veikta, izmantojot Composer, un pēc iekļaušanas konfigurācijā ir jādefinē tikai supabase disks.

Failā config/filesystems.php disku masīvā jāpievieno kaut kas līdzīgs šim:

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

Parametrs `bucket` parasti ir vienkārši Supabase informācijas panelī izveidotā krātuves kausa nosaukums (piemēram, `myapp-file-uploads`). `endpoint` ir projekta krātuves pakalpojuma bāzes URL, kas ir redzams arī atbilstošajā informācijas paneļa sadaļā un parasti ir atvasināts no projekta URL un reģiona.

Opcija `public` norāda, vai konteinera saturs pēc noklusējuma tiks uzskatīts par publisku. Ja `true`, adapteris ģenerēs pieejamus URL bez īpaša paraksta; ja `false`, tiek aktivizēta opcija `defaultUrlGeneration`, kas var piespiest ģenerēt parakstītus URL ar derīguma termiņu, kas norādīts `signedUrlExpires`. Šī konfigurācija ļauj līdzsvarot drošību un ērtības atkarībā no apstrādāto failu veida.

Vispārīgais diska URL parasti tiek atstāts kā nulle, lai adapteris to automātiski iegūtu no galapunkta. Jums tas jāmaina tikai tad, ja izmantojat starpniekserveri vai CDN un vēlaties, lai ģenerētie maršruti norādītu uz šo domēnu, nevis uz vietējo Supabase domēnu.

Augšupielādes kļūdu novēršana un Supabase Storage atslēgas izpratne

Diezgan izplatīta problēma, mēģinot augšupielādēt failus Supabase Storage no Laravel, ir tādi ziņojumi kā “Nevar ierakstīt failu atrašanās vietā: augšupielādes/…” . Tas parasti norāda, ka, lai gan draiveris ir konfigurēts, Supabase liedz rakstīšanas darbību nepietiekamu atļauju vai nepareizas atslēgas konfigurācijas dēļ.

Supabase diska konfigurācijas failā `config/filesystems.php` konfigurācija norāda, ka laukā `key` jāizmanto "privileģētā atslēga" , skaidri norādot, ka tikai lasāma atslēga nedarbosies. Tas nozīmē, ka jums ir jāizmanto pakalpojuma atslēga ar rakstīšanas atļaujām šajā nodalījumā, nevis vienkārši klienta puses publiskā API atslēga vai S3 saderības atslēga bez modifikācijas atļaujām.

Supabase panelī, API un krātuves konfigurācijas sadaļā, jūs atradīsiet gan anonīmās atslēgas, gan service_role atslēgas (vai to ekvivalentus) , kurām ir paplašinātas privilēģijas. Tieši šī pakalpojuma atslēga, nevis publiskā, jāievieto mainīgajā SUPABASE_SECRET_ACCESS_KEY, kuru draiveris pēc tam nolasīs, izmantojot env('SUPABASE_SECRET_ACCESS_KEY').

Ja esat veicis testēšanu ar S3 atslēgu no krātuves konfigurācijas vai ar projekta vispārīgajām API atslēgām, ļoti iespējams, ka šiem akreditācijas datiem nav rakstīšanas atļauju konkrētajā konteinerā, kā rezultātā rodas rakstīšanas kļūda. Atslēgas vērtības maiņa uz derīgu pakalpojuma atslēgu ar rakstīšanas atļaujām un apstiprināšana, ka konteiners pastāv un ir pareizi nosaukts, parasti novērš problēmu.

Papildus parolei ir svarīgi pārbaudīt, vai SUPABASE_STORAGE_BUCKET definētais segments precīzi atbilst Supabase saskarnē izveidotajam segmentam, ievērojot lielos un mazos burtus, un vai galapunkts atbilst pareizajam šī krātuves instances URL. Tādas detaļas kā papildu rakstzīme vai nepareizs domēns var liegt adapterim atrast failu faktisko galamērķi.

Darbplūsma ar Laravel Breeze, Blade un Supabase Storage

Kad datubāze un krātuve ir konfigurēta, nākamais loģiskais solis ir visu integrēt ar Laravel Breeze saskarni un Blade veidnēm . Tādā veidā lietotāji var reģistrēties, autentificēties un augšupielādēt failus Supabase, neizejot no Laravel ekosistēmas.

Kontrolleros jūs izmantotu krātuves fasādi , kas norāda uz supabase disku. Piemēram, lai augšupielādētu failu, kas saņemts no veidlapas ar faila ievadi, varat rīkoties šādi:

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

Šis kods norāda Laravel izmantot Supabase disku un ievietot failu virtuālajā augšupielādes mapē konfigurētajā nodalījumā. Ja atslēga un galapunkts ir pareizi, fails tiks augšupielādēts Supabase krātuvē, un jūs varēsiet izgūt tā ceļu vai ģenerēt publiskus vai parakstītus URL, izmantojot standarta krātuves metodes.

Šīs pieejas priekšrocība ir tā, ka jūsu lietojumprogramma uztur vienu saskarni glabāšanai neatkarīgi no tā, vai tā izmanto lokālo disku, Amazon S3, Supabase vai citu atbalstītu pakalpojumu. Pakalpojumu sniedzēju maiņa ir samazināta līdz konfigurācijas/filesystems.php un vides mainīgo pielāgošanai, neietekmējot biznesa loģiku.

Apvienojot to ar Blade un Breeze, jūs varat piedāvāt augšupielādes veidlapas, failu sarakstus un lejupielādes saites, kas ir pilnībā integrētas jūsu lietojumprogrammas lietotāja pieredzē. Turklāt Supabase Storage uz segmentiem un politikām balstītā pieeja ļauj izmantot tās piekļuves kontroles un drošības noteikumus , lai definētu, ko katrs lietotājs var skatīt vai lejupielādēt.

Visa šī pakotņu, draiveru un konfigurāciju ekosistēma ļauj Laravel nemanāmi sadarboties ar Supabase gan relāciju datu ar Postgres, gan failu glabāšanas, gan UUID pārvaldības ziņā . Pareizi konfigurējot atslēgas, shēmas un draiverus, tiek panākta ļoti stabila integrācija, kas novērš daudzas tipiskas kļūdas, kas rodas, mēģinot manuāli savienot abas platformas bez šiem atbalsta slāņiem.

Laravel savienošana ar Supabase datubāzei un krātuvei, īpaša Supabase draivera izmantošana UUID pārvaldībai bez galvassāpēm un Flysystem adaptera izmantošana krātuvei ļauj veidot modernas lietojumprogrammas, kurās visa sarežģītā infrastruktūra ir iekapsulēta aiz Laravel tīrās API, sākot no migrācijas un autentifikācijas līdz failu augšupielādei drošos konteineros.