Ako integrovať Supabase s Laravelom pre databázu a úložisko

Informatec Digital » Zdroje » Ako integrovať Supabase s Laravelom pre databázu a úložisko

Ak pracujete s Laravelom a ste oddaní backendové programovanie a máte chuť prejsť k databáze Spravovaný a moderný PostgreSQL ako SupabasePravdepodobne ste si všimli, že nestačí len zmeniť niekoľko premenných v súbore .env. Existujú podrobnosti o pripojení, schémach, autentifikácii a ukladaní súborov, ktoré, ak sa zanedbajú, môžu viesť k dosť záhadným chybám.

Okrem toho, ak chcete ísť o krok ďalej a použiť Supabase ako úložisko súborov Pri integrácii s úložným systémom Laravel sa veci trochu komplikujú: servisné kľúče, sektory, koncové body, vlastné ovládače Flysystem atď. Dobrou správou je, že všetko – databáza, úložisko a manipulácia s UUID – sa dá perfektne integrovať pomerne čistým spôsobom.

Pripojenie Laravelu k databáze Supabase

Prvým krokom je mať funkčný Laravel projekt a prepojiť ho s databázou Postgres, ktorú poskytuje Supabase. Na to potrebujete prostredie s Aktualizované PHP a Composer a vytvorte nový projekt alebo použite existujúci. Z konzoly jednoducho vygenerujte projekt typickým príkazom Laravelu a potom začnite nastavovať pripojenie.

Keď už máte kostru projektu, obvyklým krokom je inštalácia jednoduchého autentifikačného systému. Laravel Breeze sa do toho veľmi dobre hodí, pretože obsahuje Šablóny čepelí a základný postup prihlásenia a registrácieTo vám umožní rýchlo overiť, či je vaše databázové pripojenie správne nakonfigurované a či môžete bez problémov vytvárať používateľov.

Ak chcete získať podrobnosti o pripojení, prihláste sa do panela Supabase a vytvorte nový databázový projekt (môžete to urobiť priamo z databáza.nová(ktorý presmeruje na sprievodcu). Ak ešte nemáte účet, najprv sa zobrazí obrazovka registrácie; ak ho už máte, prejdete priamo do nastavení projektu a do sekcie, kde si môžete skontrolovať reťazec pripojenia.

Na stránke projektu v sekcii pripojenia nájdete tlačidlo ako "Pripojiť" alebo podobné. Po kliknutí naň vám Supabase zobrazí niekoľko formátov pripojovacích reťazcov (URI, jednotlivé parametre atď.). Skopírujte celé URI, ale nezabudnite, že musíte nahradiť heslo pre ten, ktorý skutočne používate v databáze, pretože sa často zobrazuje predvolený alebo zástupný symbol.

S týmito informáciami musíte prejsť do súboru .env vášho projektu Laravel a aktualizovať premenné DB_HOST, DB_PORT, DB_DATABASE, DB_USERNAME a DB_PASSWORD alebo nakonfigurovať premennú DATABASE_URL, ak uprednostňujete použitie formátu celého reťazca. Cieľom je, aby všetko ukazovalo na Klaster Supabase Postgres a nie vášmu lokálnemu hostiteľovi.

Nakonfigurujte ovládač Postgres a schému Supabase v Laraveli

V Laraveli je kľúčový súbor pre konfiguráciu databázy config/database.phpHoci môžete priamo použiť ovládač pgsql, ktorý je súčasťou frameworku, pri práci so Supabase je bežné použiť niektoré ďalšie úpravy, najmä pokiaľ ide o schémy a možnosti špecifické pre Postgres.

Typická konfigurácia pre Postgres v Laraveli môže vyzerať takto, v poli connections, pod kľúčom 'pgsql':

'pgsql' => ,

Kľúčom je tu parameter cesta_hľadaniaSupabase štandardne používa verejnú schému, ktorá je sprístupnená prostredníctvom jej API. Ak chcete, aby vaša Laravel aplikácia bola oddelená od tejto schémy a aby ste sa vyhli konfliktom tabuliek alebo politík, dôrazne sa odporúča zmeniť napríklad search_path na vašu vlastnú schému. laravel, ako je vidieť v predchádzajúcom príklade.

Týmto spôsobom budú migrácie a tabuľky generované vaším projektom vytvorené v tejto alternatívnej schéme a nie verejne. Toto oddelenie značne uľahčuje správu. bezpečnostné pravidlá, RLS a prístup z panela Supabase bez toho, aby ste šliapali na niečo, na čo by ste nemali, a pri zachovaní prehľadnosti štruktúry databázy.

Po úprave konfiguračného súboru môžete spustiť migrácie pomocou bežných príkazov Laravelu. Tým sa vytvoria overovacie tabuľky a všetky ostatné tabuľky, ktoré ste definovali. Ak je všetko správne nakonfigurované, príkazy sa spustia pre Supabase Postgres bez toho, aby ste museli robiť čokoľvek iné.

Po dokončení migrácií spustite vývojový server s príkazom `artisan serve` a skúste zaregistrovať a prihlásiť používateľov. Ak sa nezobrazia žiadne chyby pripojenia alebo migrácie, znamená to, že Laravel funguje. správna komunikácia so Supabase a môžete pokračujte v budovaní svojej obchodnej logiky normálne.

Použitie špecifického ovládača Supabase v Laraveli

Hoci štandardný ovládač pgsql funguje, existuje balík, ktorý pridáva ovládač databázy supabase pre Laravel, čím sa rozširuje správanie PostgreSQL o veľmi užitočné vylepšenia, najmä pokiaľ ide o spracovanie stĺpcov UUID a spôsob, akým sú dotazy zostavené.

Tento balík, distribuovaný ako prahsys/laravel-supabase, sa inštaluje cez Composer a registruje ďalší ovládač s názvom supabase, ktorý môžete použiť vo svojom súbore config/database.php. Interne je založený na ovládači Postgres od Laravelu, ale obsahuje nastavenia a vyhľadávacie gramatiky optimalizované pre špecifické prostredie Supabase.

Po nainštalovaní môžete v rámci sekcia pripojení:

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

Výhodou použitia tohto ovládača je, že stále získate všetok výkon enginu Postgres, ale zároveň automaticky spracováva určité chúlostivé detaily Supabase, najmä pri práci s... UUID ako primárne kľúče alebo polia vzťahovVďaka tomu sa vyhnete nutnosti manuálneho písania pretypovania pre každý zložitý dopyt.

Balík je tiež navrhnutý tak, aby dobre fungoval s modernými verziami frameworku a PHP a ponúka oficiálnu kompatibilitu s... Laravel 10.x, 11.x, 12.x a s PHP od verzie 8.1 a vyššie, ako aj s akoukoľvek štandardnou databázou PostgreSQL, vrátane samozrejme Supabase.

Aby sa zabezpečilo správne fungovanie všetkého, balík obsahuje sadu automatizovaných testov. Testy môžete spustiť pomocou príkazu `composer test`, ktorý pre rýchlosť použije databázu SQLite v pamäti, alebo pripraviť súbor `.env.testing` odkazujúci na vašu Supabase a spustiť `composer test-supabase` na overenie správania v reálnom prostredí. Vzdialený Postgres.

Správa UUID v Supabase a Laravel

Supabase má zvláštnosť so stĺpcami UUID: ak sa pokúsite porovnať UUID priamo s textovým reťazcom bez pretypovania, dotaz môže zlyhanie alebo vrátenie neočakávaných výsledkovV „obyčajnom“ systéme Postgres by ste to mohli vyriešiť globálnymi pretypovaniami alebo vlastnými operátormi, ale v Supabase tieto globálne úpravy nie sú povolené.

To znamená než priame skúmanie štýlu:

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

Nebude to fungovať ako by ste očakávali. Ak však vykonáte explicitné pretypovanie:

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

Dotaz je úspešný. Problém je v tom, že v Laraveli, keď píšete dotazy pomocou Eloquentu alebo nástroja na tvorbu dotazov, nechcete ísť vkladanie CAST do každého whereTu prichádza na rad ovládač supabase zo spomínaného balíka, ktorý sa postará o pridanie týchto pretypovaní za vás.

S aktívnym ovládačom môžete vykonávať bežné otázky as:

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

A to nielen pri priamych konzultáciách, ale aj v sa pripojíNapríklad, ak chcete načítať príspevky a spojiť ich s tabuľkou používateľov pomocou poľa UUID, môžete urobiť niečo takéto:

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

Vodič je zodpovedný za použitie potrebné prehrávať textové správy v príslušných stĺpcoch UUID, transparentne. Týmto spôsobom váš kód zostane pre Laravel idiomatický a nemusíte písať surové SQL alebo používať zvláštne triky v každom zložitom dotaze.

Ak chcete mať lepšiu kontrolu nad tým, ktoré stĺpce sa považujú za UUID, balík ponúka vlastnosť Stĺpce CastsUuid pre vaše modely Eloquent. Jednoducho ho použite v triede modelu a definujte chránené pole ďalších stĺpcov:

use Prahsys\Supabase\Traits\CastsUuidColumns;

class Post extends Model
{
    use CastsUuidColumns;

    protected $uuidColumns = ;
}

Táto vlastnosť robí tri dôležité veci: štandardne zahŕňa primárny kľúč ako UUID a pridáva akýkoľvek stĺpec, ktorý deklarujete vo vlastnosti. $uuidColumns a oznámi tieto informácie nástroju na tvorbu dotazov, aby vedel, kde má použiť pretypovania. Takto sa všetok prístup k údajom zahŕňajúci UUID stáva konzistentné a automatizované.

Pre ešte pokročilejšie prípadyMôžete zaregistrovať vlastný detektor stĺpcov s UUID. Pomocou balíka PostgresGrammar môžete zadať funkciu spätného volania, ktorá na základe názvu stĺpca alebo kontextu dotazu rozhodne, či sa má stĺpec považovať za UUID. Napríklad:

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

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

Po zavedení tejto funkcie môže systém považovať za UUID všetky stĺpce, ktorých názov má určitý vzor alebo sa nachádza v konkrétnom zozname, a prispôsobiť sa tak... veľmi špecifické konvencie pomenovávania vášho projektu.

Integrácia úložiska Supabase ako súborového systému v Laravel

Okrem databázy je potrebné v mnohých projektoch ukladať obrázky, dokumenty alebo iné súbory nahrané používateľmi. Supabase obsahuje úložnú službu založenú na kontajneroch, ktorú môžete využiť ako Laravel disk pomocou FlysystemuNa tento účel existuje špecifický adaptér, ktorý umožňuje, aby sa so Supabase Storage zaobchádzalo ako s ďalším ovládačom v rámci config/filesystems.php.

Predmetný balík poskytuje adaptér Flysystem, ktorý sa transparentne integruje s úložným systémom frameworku. Spĺňa minimálne požiadavky PHP >= 8.1, Laravel 10.x alebo 11.x a príponu PHP fileinfo (ext-fileinfo), ktorú Laravel už odporúča na prácu so súbormi. Inštalácia sa vykonáva pomocou Composera a po jej pridaní stačí v konfigurácii definovať disk supabase.

V priečinku config/filesystems.phpV rámci diskového poľa by ste pridali niečo podobné nasledujúcemu:

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

Parameter vedra je zvyčajne jednoducho názov úložného priestoru ktoré ste vytvorili v paneli Supabase (napríklad myapp-file-uploads). Koncový bod je základná URL adresa úložnej služby projektu, ktorá je viditeľná aj v príslušnej časti panela a zvyčajne je odvodená z URL adresy a regiónu projektu.

Možnosť „public“ určuje, či sa obsah kontajnera bude štandardne považovať za verejný. Ak je hodnota „true“, adaptér vygeneruje prístupné adresy URL bez špeciálneho podpisu; ak je hodnota „false“, aktivuje sa možnosť „defaultUrlGeneration“, ktorá môže vynútiť generovanie podpísaných adries URL s časom expirácie určeným v parametri „signedUrlExpires“. Táto konfigurácia umožňuje vyvážiť záťaž. bezpečnosť a pohodlie v závislosti od typu súborov, s ktorými pracujete.

Všeobecná URL adresa disku sa zvyčajne ponechá ako null, aby ju adaptér automaticky odvodil z koncového bodu. Mali by ste sa jej dotknúť iba v prípade, že používate proxy alebo sprostredkovateľská CDN a chcete, aby vygenerované trasy smerovali na túto doménu namiesto natívnej domény Supabase.

Riešenie chýb pri nahrávaní a pochopenie kľúča k úložisku Supabase

Pomerne častým problémom pri pokuse o nahranie súborov do Supabase Storage z Laravelu je prijímanie správ typu „Nedá sa zapísať súbor na adrese: uploads/…“Toto zvyčajne znamená, že hoci je ovládač nakonfigurovaný, Supabase odmieta operáciu zápisu z dôvodu nedostatočných oprávnení alebo nesprávne nakonfigurovaného kľúča.

V súbore config/filesystems.php v databáze supabase sa v konfigurácii uvádza použitie „privilegovaný kľúč“ v poli kľúča s výslovným uvedením, že kľúč iba na čítanie nebude fungovať. To znamená, že musíte použiť servisný kľúč s oprávneniami na zápis do daného úložiska, nielen verejný kľúč API určený pre klienta alebo kľúč určený pre kompatibilitu s S3 bez oprávnení na úpravu.

V paneli Supabase v sekcii konfigurácie API a úložiska nájdete anonymné kľúče aj service_role alebo ekvivalentToto sú tie s rozšírenými oprávneniami. Je to tento servisný kľúč, a nie verejný, ktorý by ste mali umiestniť do premennej SUPABASE_SECRET_ACCESS_KEY, ktorú potom ovládač prečíta prostredníctvom env('SUPABASE_SECRET_ACCESS_KEY').

Ak ste testovali s kľúčom S3 z konfigurácie úložiska alebo s generickými kľúčmi API z projektu, je veľmi pravdepodobné, že tieto prihlasovacie údaje nemajú povolenie na zápis do konkrétneho kontajnera, čo vedie k chybe zápisu. Zmena hodnoty kľúča na platný servisný kľúč s oprávneniami na zápis A potvrdením existencie vedra a jeho správneho zapísania sa problém zvyčajne vyrieši.

Okrem kľúča je dôležité overiť, či sa vedierko definované v SUPABASE_STORAGE_BUCKET presne zhoduje s vedierkou vytvorenou v rozhraní Supabase, s ohľadom na veľké a malé písmená, a či koncový bod zodpovedá správnej URL adrese pre danú inštanciu úložiska. Detail, ako napríklad nadbytočný znak alebo nesprávna doména, môže zabrániť fungovaniu adaptéra. nájsť skutočný cieľ súborov.

Pracovný postup s Laravel Breeze, Blade a Supabase Storage

Keď máte nastavenú databázu a úložisko, ďalším prirodzeným krokom je integrácia všetkého s vaším Rozhranie Laravel Breeze a šablóny BladeTýmto spôsobom sa používatelia môžu registrovať, autentifikovať a nahrávať súbory do Supabase bez toho, aby opustili ekosystém Laravelu.

V rámci vašich ovládačov by ste použili Fasáda skladovacích priestorov ukazujúci na disk supabase. Napríklad, ak chcete nahrať súbor prijatý z formulára so vstupom súboru, môžete urobiť niečo ako:

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

Tento kód povie Laravelu, aby použil disk supabase a umiestnite súbor do priečinka virtuálnych nahrávaných súborov v nakonfigurovanom konte. Ak sú kľúč a koncový bod správne, súbor sa nahrá do úložiska Supabase a vy môžete načítať jeho cestu alebo vygenerovať verejné alebo podpísané adresy URL pomocou štandardných metód úložiska.

Výhodou tohto prístupu je, že vaša aplikácia si udržiava jedno rozhranie pre úložisko bez ohľadu na to, či používa lokálny disk, Amazon S3, Supabase alebo inú podporovanú službu. Zmena poskytovateľov sa zredukuje na upraviť súbor config/filesystems.php a premenné prostredia bez toho, aby sa dotkli obchodnej logiky.

Kombináciou s Blade a Breeze môžete ponúknuť formuláre na nahrávanie, zoznamy súborov a odkazy na stiahnutie plne integrované do používateľského rozhrania vašej aplikácie. Okrem toho vám prístup Supabase Storage založený na vedierkach a politikách umožňuje využiť jeho kontroly prístupu a bezpečnostné pravidlá definovať, čo si každý používateľ môže zobraziť alebo stiahnuť.

Celý tento ekosystém balíkov, ovládačov a konfigurácií umožňuje Laravelu veľmi pohodlne pracovať so Supabase, a to ako v aspekte relačných dát s Postgres, tak aj v... ukladanie súborov a správa UUIDSprávnym nastavením kľúčov, schém a ovládačov dosiahnete veľmi solídnu integráciu, ktorá sa vyhne mnohým typickým chybám, ku ktorým dochádza pri pokuse o manuálne prepojenie oboch platforiem bez týchto vrstiev pomoci.

Prepojenie Laravelu so Supabase pre databázu a úložisko, využitie špecializovaného ovládača Supabase pre bezproblémovú správu UUID a použitie adaptéra Flysystem pre úložisko vám umožňuje vytvárať moderné aplikácie, kde Celá komplexná infraštruktúra je zapuzdrená V zákulisí čistého API rozhrania Laravel, od migrácií a autentifikácie až po nahrávanie súborov do zabezpečených vedier.