Kako integrirati Supabase sa Laravelom za bazu podataka i pohranu podataka

Informatec Digital » Resursi » Kako integrirati Supabase sa Laravelom za baze podataka i pohranu

Ako radite s Laravelom i posvećeni ste backend programiranju , te želite preći na modernu, upravljanu PostgreSQL bazu podataka poput Supabase-a , vjerovatno ste shvatili da puka promjena nekoliko varijabli u .env datoteci nije dovoljna. Postoje detalji o povezivanju, sheme, autentifikacija i pohrana datoteka koji, ako se zanemaruju, mogu dovesti do nekih prilično zagonetnih grešaka.

Nadalje, kada želite ići korak dalje i koristiti Supabase kao pohranu datoteka integriranu s Laravelovim diskovnim sistemom (Storage), stvari postaju malo kompliciranije: servisni ključevi, kontejneri, krajnje tačke, prilagođeni Flysystem drajveri itd. Dobra vijest je da se sve može savršeno integrirati - baza podataka, pohrana i rukovanje UUID-om - na prilično čist način.

Povezivanje Laravela sa Supabase bazom podataka

Prvi korak je imati funkcionalan Laravel projekat i povezati ga sa Postgres bazom podataka koju pruža Supabase. Za to vam je potrebno okruženje sa ažuriranim PHP-om i Composer-om , a možete kreirati novi projekat ili koristiti postojeći. Iz konzole jednostavno generirajte projekat koristeći standardnu ​​Laravel naredbu, a zatim počnite sa podešavanjem veze.

Nakon što postavite okvir projekta, uobičajena praksa je instaliranje jednostavnog sistema za autentifikaciju. Laravel Breeze se odlično uklapa jer uključuje Blade predloške i osnovni tok prijave i registracije , što vam omogućava da brzo provjerite da li je vaša veza s bazom podataka ispravno konfigurirana i da možete kreirati korisnike bez problema.

Da biste dobili detalje o povezivanju, prijavite se na svoju Supabase kontrolnu ploču i kreirajte novi projekat baze podataka (to možete učiniti direktno iz `database.new` , što preusmjerava na čarobnjaka). Ako još nemate račun, prvo ćete vidjeti ekran za registraciju; ako ga već imate, otići ćete direktno na postavke projekta i odjeljak gdje možete pronaći string za povezivanje.

Unutar stranice projekta, u odjeljku za povezivanje, naći ćete dugme "Poveži se" ili nešto slično. Klikom na njega prikazat će se nekoliko formata stringa za povezivanje (URI, pojedinačni parametri itd.). Kopirajte cijeli URI, ali ne zaboravite zamijeniti lozinku onom koju zapravo koristite za bazu podataka, jer se često prikazuje zadana lozinka ili rezervirano mjesto.

S tim informacijama, trebate otići u .env datoteku vašeg Laravel projekta i ažurirati varijable DB_HOST, DB_PORT, DB_DATABASE, DB_USERNAME i DB_PASSWORD ili konfigurirati varijablu DATABASE_URL ako želite koristiti format punog stringa. Cilj je osigurati da sve ukazuje na Supabase Postgres klaster , a ne na vaš localhost.

Konfigurišite Postgres drajver i Supabase shemu u Laravelu

U Laravelu, ključna datoteka za konfiguraciju baze podataka je config/database.php . Iako možete direktno koristiti pgsql drajver koji dolazi s frameworkom, pri radu sa Supabaseom uobičajeno je primijeniti neke dodatne postavke, posebno u vezi sa shemama i opcijama specifičnim za Postgres.

Tipična Postgres konfiguracija u Laravelu može izgledati ovako, unutar niza veza, pod ključem 'pgsql' :

'pgsql' => ,

Ključ ovdje leži u parametru `search_path` . Supabase, prema zadanim postavkama, koristi `public` shemu, koja je izložena putem svojih API-ja. Ako želite da vaša Laravel aplikacija bude odvojena od te sheme i da izbjegnete sukobe tabela ili politika, toplo se preporučuje da promijenite `search_path` u vlastitu shemu, na primjer, `laravel` , kao što je prikazano u prethodnom primjeru.

Na ovaj način, migracije i tabele generirane vašim projektom bit će kreirane u ovoj alternativnoj shemi, a ne javno. Ovo odvajanje uveliko pojednostavljuje upravljanje sigurnosnim pravilima, RLS-om i pristupom iz Supabase panela bez prepisivanja bilo čega što ne biste trebali, a istovremeno održava strukturu baze podataka organiziranom.

Nakon što ste prilagodili konfiguracijsku datoteku, možete pokrenuti migracije koristeći standardne Laravel naredbe. Ovo će kreirati tabele za autentifikaciju i sve ostale tabele koje ste definirali. Ako je sve ispravno konfigurirano, naredbe će se automatski pokrenuti na Supabase Postgres serveru.

Nakon završetka migracija, pokrenite razvojni server sa `artisan serve` i pokušajte registrovati i prijaviti korisnike. Ako se ne pojave greške u povezivanju ili migraciji, to znači da Laravel ispravno komunicira sa Supabase-om i da možete nastaviti graditi svoju poslovnu logiku kao i obično.

Korištenje specifičnog Supabase drajvera u Laravelu

Iako standardni pgsql drajver radi, postoji paket koji dodaje supabase drajver baze podataka za Laravel , proširujući ponašanje PostgreSQL-a vrlo korisnim poboljšanjima, posebno u pogledu rukovanja UUID kolonama i načina na koji se upiti konstruišu.

Ovaj paket, distribuiran kao prahsys/laravel-supabase, instalira se putem Composera i registruje dodatni drajver pod nazivom supabase koji možete koristiti u svojoj datoteci config/database.php. Interno je zasnovan na Laravelovom Postgres drajveru, ali uključuje postavke i gramatiku upita optimizovane za specifično Supabase okruženje.

Nakon instalacije, možete deklarirati nešto poput sljedećeg unutar sekcije za veze :

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

Prednost korištenja ovog drajvera je u tome što i dalje dobijate punu snagu Postgres engine-a, ali on također automatski obrađuje određene osjetljive Supabase detalje, posebno pri radu s UUID-ovima kao primarnim ključevima ili poljima za relacije . Ovo izbjegava potrebu za ručnim pisanjem pretvaranja u svaki složeni upit.

Paket je također dizajniran da se dobro uklapa s modernim verzijama frameworka i PHP-a, nudeći službenu kompatibilnost s Laravelom 10.x, 11.x i 12.x te s PHP-om od verzije 8.1 nadalje, kao i sa bilo kojom standardnom PostgreSQL bazom podataka, uključujući naravno Supabase.

Kako bi se osiguralo da sve ispravno radi, paket uključuje skup automatiziranih testova. Testove možete pokrenuti naredbom `composer test`, koja će koristiti SQLite bazu podataka u memoriji radi brzine, ili pripremiti datoteku `.env.testing` koja upućuje na vašu Supabase i pokrenuti `composer test-supabase` kako biste provjerili ponašanje u stvarnom okruženju s udaljenim Postgresom.

Upravljanje UUID-ovima u Supabaseu i Laravelu

Supabase ima jednu specifičnost s UUID kolonama: ako pokušate direktno uporediti UUID s tekstualnim nizom bez pretvaranja (casting), upit može propasti ili vratiti neočekivane rezultate . U čistom Postgres okruženju, ovo biste mogli riješiti globalnim pretvaranjima ili prilagođenim operatorima, ali Supabase ne dozvoljava takva globalna prilagođavanja.

To podrazumijeva da direktan upit o stilu:

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

Neće raditi kako biste očekivali. Međutim, ako izvršite eksplicitno pretvaranje:

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

Upit je uspješno izvršen. Problem je što u Laravelu, kada pišete upite pomoću Eloquenta ili alata za izradu upita, ne želite dodavati CAST-ove svakoj WHERE klauzuli . Tu dolazi do izražaja supabase drajver iz prethodno spomenutog paketa, koji dodaje te cast-ove umjesto vas.

Kada je taj upravljački program aktivan, možete izvršavati uobičajene upite kao što su:

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

I ne samo u direktnim upitima, već i u spajanjima . Na primjer, ako želite preuzeti objave i spojiti ih s tabelom korisnika koristeći UUID polje, mogli biste uraditi nešto ovako:

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

Drajver transparentno primjenjuje potrebne tekstualne konverzije na relevantne UUID kolone. Na ovaj način, vaš kod ostaje idiomatski za Laravel i ne morate pisati sirovi SQL ili koristiti čudne trikove u svakom složenom upitu.

Ako želite precizniju kontrolu nad time koje se kolone smatraju UUID-ovima, paket nudi osobinu CastsUuidColumns za vaše Eloquent modele. Jednostavno je koristite u svojoj klasi modela i definirajte zaštićeni niz dodatnih kolona:

use Prahsys\Supabase\Traits\CastsUuidColumns;

class Post extends Model
{
    use CastsUuidColumns;

    protected $uuidColumns = ;
}

Ova osobina radi tri važne stvari: uključuje primarni ključ kao zadani UUID, dodaje sve kolone koje deklarirate svojstvu `$uuidColumns` i komunicira ove informacije alatu za izradu upita kako bi znao gdje primijeniti pretvaranja. Ovo čini sav pristup podacima koji uključuje UUID-ove konzistentnim i automatiziranim.

Za još naprednije slučajeve , možete registrovati prilagođeni UUID detektor kolone. Koristeći PostgresGrammar iz paketa, možete odrediti funkciju povratnog poziva koja, na osnovu naziva kolone ili konteksta upita, odlučuje da li je treba tretirati kao UUID. Na primjer:

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

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

Sa ovom postavljenom funkcijom, sistem može smatrati UUID-om sve kolone čije ime ima određeni obrazac ili se nalazi unutar određene liste, prilagođavajući se vrlo specifičnim konvencijama imenovanja vašeg projekta.

Integrirajte Supabase Storage kao datotečni sistem u Laravel

Pored baze podataka, mnogi projekti trebaju pohranjivati ​​slike, dokumente ili druge datoteke koje su korisnici postavili. Supabase uključuje uslugu pohrane zasnovanu na kontejnerima koju možete koristiti kao Laravelov disk putem Flysystem-a . Dostupan je poseban adapter za tretiranje Supabase Storage-a kao dodatnog drajvera unutar config/filesystems.php.

Predmetni paket pruža Flysystem adapter koji se besprijekorno integrira sa Storage sistemom frameworka. Ispunjava minimalne zahtjeve PHP >= 8.1, Laravel 10.x i 11.x , te PHP fileinfo ekstenziju (ext-fileinfo), koju Laravel obično preporučuje za rukovanje datotekama. Instalacija se vrši pomoću Composera, a nakon uključivanja, potrebno je samo definirati supabase disk u konfiguraciji.

U datoteci config/filesystems.php , unutar niza disks, trebali biste dodati nešto slično sljedećem:

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

Parametar `bucket` je obično jednostavno naziv kontejnera za pohranu koji ste kreirali u Supabase kontrolnoj tabli (na primjer, `myapp-file-uploads`). `Krajnja tačka` je osnovni URL servisa za pohranu projekta, također vidljiv u odgovarajućem odjeljku kontrolne ploče, i obično je izveden iz URL-a i regije projekta.

Opcija `public` označava da li će se sadržaj kontejnera tretirati kao javni prema zadanim postavkama. Ako je postavljeno na `true`, adapter će generirati dostupne URL-ove bez posebnog potpisa; ako je postavljeno na `false`, opcija `defaultUrlGeneration` stupa na snagu, koja može prisiliti generiranje potpisanih URL-ova s ​​vremenom isteka određenim u `signedUrlExpires`. Ova konfiguracija vam omogućava da uravnotežite sigurnost i praktičnost ovisno o vrsti datoteka koje obrađujete.

Opći URL diska se obično ostavlja kao null tako da ga adapter automatski izvodi iz krajnje tačke. Trebali biste ga mijenjati samo ako koristite posrednički proxy ili CDN i želite da generirane rute pokazuju na tu domenu umjesto na izvornu Supabase domenu.

Rješavanje problema s greškama pri prijenosu i razumijevanje ključa Supabase Storagea

Prilično čest problem pri pokušaju učitavanja datoteka na Supabase Storage iz Laravela je primanje poruka poput „Nije moguće pisati datoteku na lokaciji: učitavanja/…“ . Ovo obično ukazuje na to da, iako je upravljački program konfiguriran, Supabase odbija operaciju pisanja zbog nedovoljnih dozvola ili neispravne konfiguracije ključa.

U konfiguracijskoj datoteci supabase diska, `config/filesystems.php`, konfiguracija specificira korištenje "privilegiranog ključa" u polju `key`, eksplicitno navodeći da ključ samo za čitanje neće raditi. To znači da trebate koristiti servisni ključ s dozvolama za pisanje u bucket, a ne samo javni API ključ na strani klijenta ili S3 ključ kompatibilnosti bez dozvola za modifikaciju.

U Supabase panelu, unutar odjeljka za konfiguraciju API-ja i pohrane, pronaći ćete i anonimne ključeve i ključeve service_role (ili njihove ekvivalente) koji imaju proširene privilegije. Upravo ovaj servisni ključ, a ne javni, trebate smjestiti u varijablu SUPABASE_SECRET_ACCESS_KEY, koju će upravljački program zatim pročitati pomoću env('SUPABASE_SECRET_ACCESS_KEY').

Ako ste testirali sa S3 ključem iz konfiguracije pohrane ili sa generičkim API ključevima projekta, vrlo je vjerovatno da ti akreditivi nemaju dozvole za pisanje u određeni bucket, što rezultira greškom pri pisanju. Promjena vrijednosti ključa u važeći servisni ključ sa dozvolama za pisanje i potvrda da bucket postoji i da je ispravno imenovan obično rješava problem.

Pored lozinke, važno je provjeriti da li se kontejner definisan u SUPABASE_STORAGE_BUCKET tačno podudara sa onim kreiranim u Supabase interfejsu, poštujući velika i mala slova, i da li krajnja tačka odgovara ispravnom URL-u za tu instancu skladišta. Detalj poput dodatnog znaka ili netačne domene može spriječiti adapter da locira stvarno odredište datoteka.

Radni tok sa Laravel Breeze, Blade i Supabase Storage-om

Nakon što ste konfigurirali bazu podataka i pohranu, sljedeći logičan korak je integracija svega s vašim Laravel Breeze interfejsom i Blade predlošcima . Na ovaj način, korisnici se mogu registrirati, autentificirati i prenositi datoteke na Supabase bez napuštanja Laravel ekosistema.

Unutar vaših kontrolera, koristili biste Storage fasadu koja pokazuje na supabase disk. Na primjer, da biste otpremili datoteku primljenu iz obrasca s ulazom datoteke, mogli biste učiniti nešto poput ovoga:

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

Ovaj kod govori Laravelu da koristi Supabase disk i smjesti datoteku unutar virtualne mape za prijenos unutar konfiguriranog spremnika. Ako su ključ i krajnja tačka ispravni, datoteka će biti prenesena u Supabase pohranu, a vi možete preuzeti njenu putanju ili generirati javne ili potpisane URL-ove koristeći standardne metode pohrane.

Prednost ovog pristupa je što vaša aplikacija održava jedan interfejs za pohranu, bez obzira da li koristi lokalni disk, Amazon S3, Supabase ili neku drugu podržanu uslugu. Promjena dobavljača svodi se na podešavanje config/filesystems.php i varijabli okruženja, bez utjecaja na poslovnu logiku.

Kombinacijom ovoga s Blade i Breeze, možete ponuditi obrasce za prijenos, popise datoteka i linkove za preuzimanje koji su potpuno integrirani u korisničko iskustvo vaše aplikacije. Nadalje, Supabase Storage pristup zasnovan na skupinama i pravilima omogućuje vam da iskoristite njegove kontrole pristupa i sigurnosna pravila kako biste definirali što svaki korisnik može pregledati ili preuzeti.

Cijeli ovaj ekosistem paketa, drajvera i konfiguracija omogućava Laravelu da besprijekorno radi sa Supabase-om, kako u pogledu relacijskih podataka s Postgres-om, tako i u pogledu pohrane datoteka i upravljanja UUID-ovima . Pravilnim konfigurisanjem ključeva, shema i drajvera postiže se vrlo robusna integracija koja izbjegava mnoge tipične greške koje se javljaju pri pokušaju ručnog povezivanja obje platforme bez ovih pratećih slojeva.

Povezivanje Laravela sa Supabase-om za bazu podataka i pohranu, korištenje namjenskog Supabase drajvera za upravljanje UUID-ovima bez glavobolja i korištenje Flysystem adaptera za pohranu omogućava vam izgradnju modernih aplikacija gdje je sva složena infrastruktura enkapsulirana iza Laravelovog čistog API-ja, od migracija i autentifikacije do otpremanja datoteka u sigurne bucket-ove.