Jak integrovat Supabase s Laravelem pro databázi a úložiště

Informatec Digital » Zdroje » Jak integrovat Supabase s Laravelem pro databáze a úložiště

Pokud pracujete s Laravelem a věnujete se backendovému programování a chcete přejít na moderní, spravovanou databázi PostgreSQL, jako je Supabase , pravděpodobně jste si uvědomili, že pouhá změna několika proměnných v souboru .env nestačí. Existují podrobnosti o připojení, schémata, ověřování a ukládání souborů, které, pokud se zanedbají, mohou vést k některým poněkud záhadným chybám.

Navíc, pokud chcete jít ještě o krok dál a použít Supabase jako úložiště souborů integrované s diskovým systémem Laravelu (Storage), věci se trochu komplikují: servisní klíče, buckety, koncové body, vlastní ovladače Flysystem atd. Dobrou zprávou je, že vše lze perfektně integrovat – databázi, úložiště a práci s UUID – poměrně čistým způsobem.

Propojení Laravelu s databází Supabase

Prvním krokem je mít funkční projekt Laravel a propojit ho s databází Postgres od Supabase. K tomu potřebujete prostředí s aktualizovaným PHP a Composerem a můžete vytvořit nový projekt nebo použít existující. Z konzole jednoduše vygenerujte projekt pomocí standardního příkazu Laravel a poté začněte nastavovat připojení.

Jakmile máte nastavený rámec projektu, obvyklou praxí je instalace jednoduchého ověřovacího systému. Laravel Breeze se do něj velmi dobře hodí, protože obsahuje šablony Blade a základní proces přihlášení a registrace , což vám umožňuje rychle ověřit, zda je připojení k databázi správně nakonfigurováno a zda můžete bez problémů vytvářet uživatele.

Chcete-li získat podrobnosti o připojení, přihlaste se do dashboardu Supabase a vytvořte nový databázový projekt (můžete to provést přímo z `database.new` , který přesměruje na průvodce). Pokud ještě nemáte účet, nejprve se zobrazí registrační obrazovka; pokud již účet máte, přejdete přímo do nastavení projektu a do sekce, kde najdete připojovací řetězec.

Na stránce projektu v sekci připojení najdete tlačítko „Připojit“ nebo něco podobného. Kliknutím na něj se zobrazí několik formátů připojovacích řetězců (URI, jednotlivé parametry atd.). Zkopírujte celé URI, ale nezapomeňte nahradit heslo heslem , které skutečně používáte pro databázi, protože se často zobrazuje výchozí heslo nebo zástupný symbol.

S těmito informacemi musíte přejít do souboru .env vašeho projektu Laravel a aktualizovat proměnné DB_HOST, DB_PORT, DB_DATABASE, DB_USERNAME a DB_PASSWORD, nebo nakonfigurovat proměnnou DATABASE_URL, pokud dáváte přednost použití formátu plného řetězce. Cílem je zajistit, aby vše ukazovalo na cluster Supabase Postgres a nikoli na váš localhost.

Nakonfigurujte ovladač Postgres a schéma Supabase v Laravelu

V Laravelu je klíčovým souborem pro konfiguraci databáze config/database.php . I když můžete přímo použít ovladač pgsql, který je součástí frameworku, při práci se Supabase je běžné použít některá další nastavení, zejména pokud jde o schémata a možnosti specifické pro Postgres.

Typická konfigurace Postgresu v Laravelu by mohla vypadat takto, v poli connections, pod klíčem 'pgsql' :

'pgsql' => ,

Klíč spočívá v parametru `search_path` . Supabase ve výchozím nastavení používá schéma `public`, které je zpřístupněno prostřednictvím jejích API. Pokud chcete, aby vaše aplikace Laravel byla od tohoto schématu oddělená a aby se zabránilo konfliktům tabulek nebo zásad, důrazně doporučujeme změnit `search_path` na vaše vlastní schéma, například `laravel` , jak je vidět v předchozím příkladu.

Tímto způsobem budou migrace a tabulky generované vaším projektem vytvořeny v tomto alternativním schématu a ne veřejně. Toto oddělení výrazně zjednodušuje správu bezpečnostních pravidel, RLS a přístupu z panelu Supabase, aniž by se přepisovalo cokoli, co byste neměli, a zároveň se zachovává organizovaná struktura databáze.

Jakmile upravíte konfigurační soubor, můžete spustit migrace pomocí standardních příkazů Laravelu. Tím se vytvoří ověřovací tabulky a všechny další tabulky, které jste definovali. Pokud je vše správně nakonfigurováno, příkazy se automaticky spustí na serveru Supabase Postgres.

Po dokončení migrací spusťte vývojový server s příkazem `artisan serve` a zkuste zaregistrovat a přihlásit uživatele. Pokud se neobjeví žádné chyby připojení ani migrace, znamená to, že Laravel správně komunikuje se Supabase a můžete pokračovat v budování obchodní logiky jako obvykle.

Použití specifického ovladače Supabase v Laravelu

Ačkoliv standardní ovladač pgsql funguje, existuje balíček, který přidává ovladač databáze supabase pro Laravel , čímž rozšiřuje chování PostgreSQL o velmi užitečná vylepšení, zejména pokud jde o zpracování sloupců UUID a způsob konstrukce dotazů.

Tento balíček, distribuovaný jako prahsys/laravel-supabase, se instaluje přes Composer a registruje další ovladač s názvem supabase, který můžete použít v souboru config/database.php. Interně je založen na ovladači Postgres od Laravelu, ale obsahuje nastavení a gramatiku dotazů optimalizovanou pro specifické prostředí Supabase.

Po instalaci můžete v sekci connections deklarovat něco jako následující :

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

Výhodou použití tohoto ovladače je, že stále získáte plný výkon enginu Postgres, ale zároveň automaticky zpracovává určité citlivé detaily Supabase, zejména při práci s UUID jako primárními klíči nebo poli relací . Díky tomu se vyhnete nutnosti ručního přetypování v každém složitém dotazu.

Balíček je také navržen tak, aby dobře fungoval s moderními verzemi frameworku a PHP, a nabízí oficiální kompatibilitu s Laravel 10.x, 11.x a 12.x a s PHP od verze 8.1 a dále, stejně jako s jakoukoli standardní databází PostgreSQL, včetně samozřejmě Supabase.

Aby vše fungovalo správně, balíček obsahuje sadu automatizovaných testů. Testy můžete spustit příkazem `composer test`, který pro rychlost použije databázi SQLite v paměti, nebo připravit soubor `.env.testing` odkazující na vaši Supabase a spustit `composer test-supabase` pro ověření chování v reálném prostředí se vzdáleným Postgresem.

Správa UUID v Supabase a Laravelu

Supabase má se sloupci UUID jednu zvláštnost: pokud se pokusíte porovnat UUID přímo s textovým řetězcem bez přetypování, dotaz může selhat nebo vrátit neočekávané výsledky . V holém prostředí Postgres byste to mohli vyřešit globálními přetypováními nebo vlastními operátory, ale Supabase takové globální úpravy neumožňuje.

To znamená , že přímý dotaz na styl:

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

Nebude to fungovat tak, jak byste očekávali. Pokud ale provedete explicitní přetypování:

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

Dotaz je úspěšný. Problém je v tom, že v Laravelu, když píšete dotazy pomocí Eloquentu nebo builderu dotazů, nechcete přidávat přetypování CAST do každé klauzule WHERE . Proto přichází na řadu ovladač supabase z výše zmíněného balíčku, který tato přetypování přidá za vás.

S aktivním ovladačem můžete provádět běžné dotazy , jako například:

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

A to nejen v přímých dotazech, ale i ve spojeních . Například, pokud chcete načíst příspěvky a spojit je s tabulkou users pomocí pole UUID, můžete udělat něco takového:

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

Ovladač transparentně aplikuje potřebné textové přetypování na příslušné sloupce UUID. Tímto způsobem zůstává váš kód pro Laravel idiomatický a nemusíte psát surové SQL nebo používat podivné triky v každém složitém dotazu.

Pokud chcete mít jemnější kontrolu nad tím, které sloupce jsou považovány za UUID, balíček nabízí vlastnost CastsUuidColumns pro vaše modely Eloquent. Jednoduše ji použijte ve své třídě modelu a definujte chráněné pole dalších sloupců:

use Prahsys\Supabase\Traits\CastsUuidColumns;

class Post extends Model
{
    use CastsUuidColumns;

    protected $uuidColumns = ;
}

Tato vlastnost dělá tři důležité věci: zahrnuje primární klíč jako výchozí UUID, přidává všechny sloupce, které deklarujete, do vlastnosti `$uuidColumns` a sděluje tyto informace nástroji pro tvorbu dotazů, aby věděl, kam použít přetypování. Díky tomu je veškerý přístup k datům zahrnující UUID konzistentní a automatizovaný.

V ještě složitějších případech si můžete zaregistrovat vlastní detektor sloupců s UUID. Pomocí PostgresGrammar z balíčku můžete zadat funkci zpětného volání, která na základě názvu sloupce nebo kontextu dotazu rozhodne, zda má být sloupec považován za UUID. Například:

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

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

S touto nastavenou funkcí může systém považovat za UUID všechny sloupce, jejichž název má určitý vzor nebo se nachází v určitém seznamu, a přizpůsobit se tak velmi specifickým konvencím pojmenování vašeho projektu.

Integrace úložiště Supabase jako souborového systému v Laravelu

Kromě databáze potřebuje mnoho projektů ukládat obrázky, dokumenty nebo jiné soubory nahrané uživateli. Supabase obsahuje úložnou službu založenou na bucketech, kterou můžete použít jako disk Laravelu prostřednictvím Flysystem . Pro zpracování úložiště Supabase jako dalšího ovladače v souboru config/filesystems.php je k dispozici specifický adaptér.

Daný balíček poskytuje adaptér Flysystem, který se bezproblémově integruje s úložným systémem frameworku. Splňuje minimální požadavky PHP >= 8.1, Laravel 10.x a 11.x a příponu PHP fileinfo (ext-fileinfo), kterou Laravel obvykle doporučuje pro práci se soubory. Instalace se provádí pomocí Composeru a po jeho přidání stačí v konfiguraci definovat disk supabase.

V souboru config/filesystems.php , v rámci pole disks, byste přidali něco podobného jako následující:

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

Parametr `bucket` je obvykle jednoduše název úložného prostoru, který jste vytvořili v dashboardu Supabase (například `myapp-file-uploads`). `Endpoint` je základní URL úložné služby projektu, která je také viditelná v odpovídající části dashboardu a obvykle je odvozena z URL a regionu projektu.

Možnost `public` určuje, zda bude obsah kontejneru ve výchozím nastavení považován za veřejný. Pokud je hodnota `true`, adaptér bude generovat přístupné URL bez speciálního podpisu; pokud je hodnota `false`, aktivuje se možnost `defaultUrlGeneration`, která může vynutit generování podepsaných URL s dobou platnosti určenou parametrem `signedUrlExpires`. Tato konfigurace umožňuje vyvážit zabezpečení a pohodlí v závislosti na typu souborů, které zpracováváte.

Obecná adresa URL disku se obvykle ponechává jako null, aby ji adaptér automaticky odvodil z koncového bodu. Měli byste ji upravit pouze v případě, že používáte zprostředkující proxy nebo CDN a chcete, aby generované trasy odkazovaly na tuto doménu místo na nativní doménu Supabase.

Řešení chyb při nahrávání a pochopení klíčových funkcí úložiště Supabase

Poměrně častým problémem při pokusu o nahrání souborů do Supabase Storage z Laravelu je zobrazování zpráv typu „Unable to write file at location: uploads/…“ . To obvykle znamená, že ačkoli je ovladač nakonfigurován, Supabase odmítá operaci zápisu z důvodu nedostatečných oprávnění nebo nesprávné konfigurace klíče.

V konfiguračním souboru disku Supabase, `config/filesystems.php`, je v poli `key` uvedeno použití „privilegovaného klíče“ , který explicitně uvádí, že klíč pouze pro čtení nebude fungovat. To znamená, že je nutné použít servisní klíč s oprávněním k zápisu do úložiště, nikoli pouze veřejný klíč API na straně klienta nebo klíč kompatibility S3 bez oprávnění k úpravám.

V panelu Supabase, v sekci konfigurace API a úložiště, najdete anonymní klíče i klíče service_role (nebo jejich ekvivalenty) , které mají rozšířená oprávnění. Právě tento servisní klíč, nikoli veřejný, byste měli umístit do proměnné SUPABASE_SECRET_ACCESS_KEY, kterou ovladač poté přečte pomocí env('SUPABASE_SECRET_ACCESS_KEY').

Pokud jste testovali s klíčem S3 z konfigurace úložiště nebo s generickými klíči API projektu, je velmi pravděpodobné, že tyto přihlašovací údaje nemají oprávnění k zápisu do konkrétního úložiště, což vede k chybě zápisu. Změna hodnoty klíče na platný servisní klíč s oprávněními k zápisu a ověření, že úložiště existuje a je správně pojmenováno, obvykle problém vyřeší.

Kromě hesla je důležité ověřit, zda se úložiště definované v SUPABASE_STORAGE_BUCKET přesně shoduje s úložištěm vytvořeným v rozhraní Supabase, s ohledem na velká a malá písmena, a zda koncový bod odpovídá správné URL pro danou instanci úložiště. Detaily, jako je například nadbytečný znak nebo nesprávná doména, mohou adaptéru zabránit v nalezení skutečného cíle souborů.

Pracovní postup s Laravel Breeze, Blade a úložištěm Supabase

Jakmile máte nakonfigurovanou databázi a úložiště, dalším logickým krokem je integrace všeho s rozhraním Laravel Breeze a šablonami Blade . Tímto způsobem se uživatelé mohou registrovat, ověřovat a nahrávat soubory do Supabase, aniž by opustili ekosystém Laravelu.

V rámci vašich kontrolerů byste použili fasádu Storage odkazující na disk supabase. Například pro nahrání souboru přijatého z formuláře se vstupem typu soubor byste mohli udělat něco jako:

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

Tento kód říká Laravelu, aby použil disk Supabase a umístil soubor do virtuální složky pro nahrávání v nakonfigurovaném bucketu. Pokud jsou klíč a koncový bod správné, soubor bude nahrán do úložiště Supabase a vy můžete načíst jeho cestu nebo vygenerovat veřejné či podepsané URL pomocí standardních metod ukládání.

Výhodou tohoto přístupu je, že vaše aplikace si udržuje jedno rozhraní pro úložiště, bez ohledu na to, zda používá lokální disk, Amazon S3, Supabase nebo jinou podporovanou službu. Přepínání poskytovatelů se omezuje na úpravu souboru config/filesystems.php a proměnných prostředí, aniž by to ovlivnilo obchodní logiku.

Kombinací s Blade a Breeze můžete nabídnout formuláře pro nahrávání, seznamy souborů a odkazy ke stažení plně integrované do uživatelského prostředí vaší aplikace. Přístup Supabase Storage založený na sektorech a zásadách vám navíc umožňuje využít jeho řízení přístupu a bezpečnostní pravidla k definování toho, co si každý uživatel může prohlížet nebo stahovat.

Celý tento ekosystém balíčků, ovladačů a konfigurací umožňuje Laravelu bezproblémovou spolupráci se Supabase, a to jak z hlediska relačních dat s Postgres, tak i ukládání souborů a správy UUID . Správnou konfigurací klíčů, schémat a ovladačů dosáhnete velmi robustní integrace, která se vyhne mnoha typickým chybám, ke kterým dochází při pokusu o ruční propojení obou platforem bez těchto podpůrných vrstev.

Propojení Laravelu se Supabase pro databázi a úložiště, využití specializovaného ovladače Supabase pro správu UUID bez problémů a použití adaptéru Flysystem pro úložiště vám umožňuje vytvářet moderní aplikace, kde je veškerá komplexní infrastruktura zapouzdřena za čistým API Laravelu, od migrací a autentizace až po nahrávání souborů do zabezpečených bucketů.