Hogyan integrálható a Supabase a Laravel-lel adatbázis és tárolás céljából?

Informatec Digital » Források » Hogyan integrálható a Supabase a Laravel-lel adatbázisok és tárolás céljából

Ha Laravel-lel dolgozol, és elkötelezett vagy a backend programozás iránt, és szeretnél átállni egy modern, menedzselt PostgreSQL adatbázisra , mint például a Supabase , akkor valószínűleg rájöttél, hogy nem elég egyszerűen néhány változót megváltoztatni az .env fájlban. Vannak olyan kapcsolati részletek, sémák, hitelesítés és fájltárolás, amelyek elhanyagolása meglehetősen rejtélyes hibákhoz vezethet.

Továbbá, ha egy lépéssel tovább szeretnél menni, és a Supabase-t a Laravel lemezrendszerével (Storage) integrált fájltárolóként szeretnéd használni , a dolgok kicsit bonyolultabbá válnak: szolgáltatáskulcsok, vödrök, végpontok, egyéni Flysystem illesztőprogramok stb. A jó hír az, hogy minden tökéletesen integrálható – az adatbázis, a tároló és az UUID-kezelés – viszonylag tiszta módon.

Laravel csatlakoztatása a Supabase adatbázishoz

Az első lépés egy működő Laravel projekt létrehozása és annak összekapcsolása a Supabase által biztosított Postgres adatbázissal. Ehhez egy frissített PHP-vel és Composerrel rendelkező környezetre van szükség , és létrehozhatsz egy új projektet, vagy használhatsz egy meglévőt. A konzolon egyszerűen generáld a projektet a standard Laravel parancs használatával, majd kezdd el a kapcsolat beállítását.

Miután a projekt keretrendszere elkészült, a szokásos gyakorlat egy egyszerű hitelesítési rendszer telepítése. A Laravel Breeze nagyon jól illeszkedik ehhez, mivel Blade sablonokat és egy alapvető bejelentkezési és regisztrációs folyamatot tartalmaz , amely lehetővé teszi az adatbázis-kapcsolat megfelelő konfigurálásának gyors ellenőrzését, és azt, hogy problémamentesen létrehozhatsz felhasználókat.

A kapcsolati adatok megszerzéséhez jelentkezz be a Supabase irányítópultra, és hozz létre egy új adatbázis-projektet (ezt közvetlenül a `database.new` fájlból teheted meg , amely átirányít a varázslóhoz). Ha még nincs fiókod, először a regisztrációs képernyő jelenik meg; ha már van, akkor közvetlenül a projekt beállításaihoz és ahhoz a részhez jutsz, ahol megtalálod a kapcsolati karakterláncot.

A projektoldalon, a kapcsolatok részben találsz egy „Kapcsolódás” gombot vagy valami hasonlót. Erre kattintva több kapcsolódási karakterlánc-formátum (URI, egyedi paraméterek stb.) jelenik meg. Másold ki a teljes URI-t, de ne felejtsd el a jelszót lecserélni arra, amelyiket ténylegesen használsz az adatbázishoz, mivel gyakran egy alapértelmezett jelszó vagy helyőrző jelenik meg.

Ezekkel az információkkal a Laravel projekted .env fájljában frissítened kell a DB_HOST, DB_PORT, DB_DATABASE, DB_USERNAME és DB_PASSWORD változókat, vagy konfigurálnod kell a DATABASE_URL változót, ha a teljes karakterlánc formátumot szeretnéd használni. A cél az, hogy minden a Supabase Postgres klaszterre mutasson , ne pedig a localhostodra.

Konfigurálja a Postgres illesztőprogramot és a Supabase sémát Laravelben

Laravelben az adatbázis konfigurációjának kulcsfájlja a config/database.php . Bár közvetlenül használhatod a keretrendszerhez tartozó pgsql illesztőprogramot, a Supabase használatakor gyakori, hogy további beállításokat alkalmazunk, különösen a sémákkal és a Postgres-specifikus opciókkal kapcsolatban.

Egy tipikus Postgres konfiguráció Laravelben így nézhet ki a connections tömbön belül, a 'pgsql' kulcs alatt :

'pgsql' => ,

A kulcs itt a `search_path` paraméterben rejlik . A Supabase alapértelmezés szerint a `public` sémát használja, amely az API-kon keresztül elérhető. Ha a Laravel alkalmazást külön szeretnéd tartani ettől a sémától, és el szeretnéd kerülni a tábla- vagy szabályzatütközéseket, erősen ajánlott a `search_path` paramétert a saját sémára módosítani, például `laravel`-re , ahogy az az előző példában is látható.

Így a projekted által generált migrációk és táblázatok ebben az alternatív sémában jönnek létre, és nem nyilvánosan. Ez az elkülönítés nagyban leegyszerűsíti a biztonsági szabályok, az RLS és a Supabase panelről történő hozzáférés kezelését anélkül, hogy bármit is felülírna, amit nem kellene, miközben az adatbázis-struktúra rendezett marad.

Miután beállítottad a konfigurációs fájlt, futtathatod a migrációkat a Laravel szabványos parancsaival. Ez létrehozza a hitelesítési táblákat és az összes többi általad definiált táblát. Ha minden helyesen van konfigurálva, a parancsok automatikusan lefutnak a Supabase Postgres szerveren.

Miután a migrációk befejeződtek, indítsd el a fejlesztői szervert az `artisan serve` paranccsal, és próbáld meg regisztrálni és bejelentkezni a felhasználókat. Ha nem jelennek meg kapcsolódási vagy migrációs hibák, az azt jelenti, hogy a Laravel megfelelően kommunikál a Supabase-szel , és folytathatod az üzleti logika felépítését a szokásos módon.

Egy adott Supabase illesztőprogram használata Laravelben

Bár a szabványos pgsql illesztőprogram működik, létezik egy csomag, amely egy supabase adatbázis-illesztőprogramot ad hozzá a Laravelhez , kiterjesztve a PostgreSQL viselkedését nagyon hasznos fejlesztésekkel, különösen az UUID oszlopok kezelése és a lekérdezések felépítése tekintetében.

Ez a prahsys/laravel-supabase néven terjesztett csomag a Composer segítségével települ, és regisztrál egy további, supabase nevű illesztőprogramot, amelyet a config/database.php fájlban használhatsz. Belsőleg a Laravel Postgres illesztőprogramján alapul, de az adott Supabase környezetre optimalizált beállításokat és lekérdezési nyelvtanokat tartalmaz.

A telepítés után a connections részben deklarálhatsz valami ilyesmit :

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

Ennek az illesztőprogramnak az az előnye, hogy továbbra is hozzáférhetsz a Postgres motor teljes erejéhez, de automatikusan kezel bizonyos kényes Supabase részleteket is, különösen akkor, ha UUID-kat használsz elsődleges kulcsként vagy kapcsolatmezőként . Ezáltal elkerülhető, hogy minden összetett lekérdezésben manuálisan kelljen megadni a konverziót.

A csomagot úgy tervezték, hogy jól illeszkedjen a keretrendszer és a PHP modern verzióihoz, hivatalos kompatibilitást kínálva a Laravel 10.x, 11.x és 12.x verzióival , valamint a PHP 8.1-es verziójától kezdődő verzióival, és bármilyen szabványos PostgreSQL adatbázissal, beleértve természetesen a Supabase-t is.

Annak érdekében, hogy minden megfelelően működjön, a csomag automatizált teszteket tartalmaz. A teszteket a `composer test` paranccsal futtathatod, amely egy memóriában lévő SQLite adatbázist használ a sebesség érdekében, vagy előkészíthetsz egy `.env.testing` fájlt, amely a Supabase-edre mutat, és futtathatod a `composer test-supabase` parancsot a viselkedés ellenőrzéséhez egy valós környezetben távoli Postgres segítségével.

UUID kezelés Supabase-ben és Laravelben

A Supabase-nek van egy sajátossága az UUID oszlopokkal: ha egy UUID-t közvetlenül egy szöveges karakterlánccal próbálsz összehasonlítani konvertálás nélkül, a lekérdezés sikertelen lehet, vagy váratlan eredményeket adhat vissza . Egy egyszerű Postgres környezetben ezt globális konverziókkal vagy egyéni operátorokkal megoldhatnád, de a Supabase nem engedélyezi az ilyen globális testreszabásokat.

Ez azt jelenti , hogy a stílus közvetlen lekérdezése:

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

Nem fog úgy működni , ahogy várnád. Ha azonban explicit módon végzed a szereposztást:

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

A lekérdezés sikeres. A probléma az, hogy Laravelben, amikor az Eloquenttel vagy a lekérdezéskészítővel írunk lekérdezéseket, nem szeretnénk minden WHERE záradékhoz CAST-eket hozzáadni . Itt jön be a képbe a fent említett csomag supabase illesztőprogramja, amely hozzáadja ezeket a konverziókat.

Ha az illesztőprogram aktív, akkor olyan gyakori lekérdezéseket hajthat végre , mint például:

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

És nem csak közvetlen lekérdezésekben, hanem illesztésekben is . Például, ha bejegyzéseket szeretnél lekérni és egy UUID mező használatával összekapcsolni a felhasználók táblájával, akkor valami ilyesmit tehetsz:

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

A driver transzparens módon kezeli a szükséges szövegátalakítások alkalmazását a releváns UUID oszlopokra. Így a kódod idiomatikus marad a Laravel számára, és nem kell nyers SQL-t írnod, vagy furcsa trükköket alkalmaznod minden összetett lekérdezésben.

Ha pontosabb szabályozást szeretne afelett, hogy mely oszlopok minősülnek UUID-nak, a csomag a CastsUuidColumns tulajdonságot kínálja az Eloquent modellekhez. Egyszerűen használja a modellosztályában, és definiáljon egy további oszlopokból álló védett tömböt:

use Prahsys\Supabase\Traits\CastsUuidColumns;

class Post extends Model
{
    use CastsUuidColumns;

    protected $uuidColumns = ;
}

Ez a tulajdonság három fontos dolgot valósít meg: az elsődleges kulcsot alapértelmezett UUID-ként használja, hozzáadja a deklarált oszlopokat az `$uuidColumns` tulajdonsághoz , és ezt az információt közli a lekérdezésszerkesztővel, hogy az tudja, hová alkalmazza a konverziókat. Ezáltal az UUID-kat érintő összes adathozzáférés konzisztens és automatizált lesz.

Még bonyolultabb esetekben regisztrálhat egyéni UUID oszlopdetektort. A csomagban található PostgresGrammar használatával megadhat egy visszahívó függvényt, amely az oszlop neve vagy a lekérdezési kontextus alapján eldönti, hogy azt UUID-ként kell-e kezelni. Például:

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

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

Ezzel a függvénnyel a rendszer UUID-ként tud tekinteni minden olyan oszlopot, amelynek neve egy bizonyos mintázattal rendelkezik, vagy egy adott listán belül van, alkalmazkodva a projekt nagyon specifikus elnevezési konvencióihoz .

A Supabase Storage integrálása fájlrendszerként Laravelben

Az adatbázis mellett számos projektnek képeket, dokumentumokat vagy a felhasználók által feltöltött egyéb fájlokat is tárolnia kell. A Supabase tartalmaz egy vödör alapú tárolási szolgáltatást, amelyet a Flysystemen keresztül Laravel lemezként használhatsz . Egy speciális adapter érhető el, amely a Supabase Storage-ot további illesztőprogramként kezeli a config/filesystems.php fájlon belül.

A szóban forgó csomag egy Flysystem adaptert biztosít, amely zökkenőmentesen integrálódik a keretrendszer tárolórendszerével. Megfelel a PHP >= 8.1, a Laravel 10.x és 11.x minimális követelményeinek , valamint a PHP fileinfo kiterjesztésnek (ext-fileinfo), amelyet a Laravel általában a fájlkezeléshez ajánl. A telepítés a Composer segítségével történik, és a beillesztés után csak a supabase lemezt kell definiálni a konfigurációban.

A config/filesystems.php fájlban , a disks tömbben, valami ehhez hasonlót kellene hozzáadnod:

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

A `bucket` paraméter általában egyszerűen a Supabase irányítópulton létrehozott tárolóvödör neve (például `myapp-file-uploads`). Az `endpoint` a projekt tárolószolgáltatásának alap URL-címe, amely az irányítópult megfelelő részében is látható, és általában a projekt URL-címéből és régiójából származik.

A `public` opció azt jelzi, hogy a vödör tartalma alapértelmezés szerint nyilvánosként legyen-e kezelve. Ha `true` az értéke, az illesztő speciális aláírás nélküli, hozzáférhető URL-eket generál; ha `false`, akkor a `defaultUrlGeneration` opció lép életbe, amely kikényszerítheti az aláírt URL-ek generálását a `signedUrlExpires` által meghatározott lejárati idővel. Ez a konfiguráció lehetővé teszi a biztonság és a kényelem egyensúlyának megteremtését a kezelt fájlok típusától függően.

Az általános lemez URL-címét általában üresen hagyjuk, így az illesztő automatikusan a végpontból származtatja. Csak akkor módosítsa, ha közbenső proxyt vagy CDN-t használ , és azt szeretné, hogy a generált útvonalak erre a tartományra mutassanak a natív Supabase tartomány helyett.

Feltöltési hibák elhárítása és a Supabase Storage kulcsának megértése

Egy meglehetősen gyakori probléma, amikor Laravelből próbálunk feltölteni fájlokat a Supabase Storage-ba, az olyan üzenetek, mint például a „Nem lehet írni a fájlt a következő helyen: feltöltések/…” . Ez általában azt jelzi, hogy bár az illesztőprogram konfigurálva van, a Supabase nem engedélyezi az írási műveletet a nem megfelelő jogosultságok vagy a kulcs helytelen konfigurációja miatt.

A supabase lemezkonfigurációs fájljában, a `config/filesystems.php`-ben a konfiguráció egy „privilegizált kulcs” használatát határozza meg a `key` mezőben, explicit módon kijelentve, hogy a csak olvasható kulcs nem fog működni. Ez azt jelenti, hogy egy írási jogosultsággal rendelkező szolgáltatáskulcsot kell használnod a tárolóhoz, nem egyszerűen egy kliensoldali nyilvános API-kulcsot vagy egy módosítási jogosultságok nélküli S3 kompatibilitási kulcsot.

A Supabase panelen, az API és tárolási konfiguráció részben megtalálod mind az anonim kulcsokat, mind a service_role kulcsokat (vagy azok megfelelőit) , amelyek kiterjesztett jogosultságokkal rendelkeznek. Ezt a szolgáltatáskulcsot, nem a nyilvánosat, kell a SUPABASE_SECRET_ACCESS_KEY változóba helyezned, amelyet az illesztőprogram ezután az env('SUPABASE_SECRET_ACCESS_KEY') használatával olvas be.

Ha a tárolási konfigurációból származó S3 kulccsal vagy a projekt általános API-kulcsaival tesztelted a rendszert, akkor nagyon valószínű, hogy ezek a hitelesítő adatok nem rendelkeznek írási jogosultsággal az adott tárolóhoz, ami írási hibát eredményez. A kulcs értékének érvényes, írási jogosultsággal rendelkező szolgáltatáskulcsra való módosítása , valamint a tároló létezésének és helyes elnevezésének megerősítése általában megoldja a problémát.

A jelszó mellett fontos ellenőrizni, hogy a SUPABASE_STORAGE_BUCKET-ben definiált tárolóegység pontosan megegyezik-e a Supabase felületen létrehozottal, tiszteletben tartva a nagy- és kisbetűket, és hogy a végpont megfelel-e az adott tárolási példány megfelelő URL-címének. Egy olyan részlet, mint egy extra karakter vagy egy helytelen domain, megakadályozhatja, hogy az illesztő megtalálja a fájlok tényleges célhelyét.

Munkafolyamat Laravel Breeze, Blade és Supabase Storage használatával

Miután beállítottad az adatbázist és a tárhelyet, a következő logikus lépés az, hogy mindent integrálj a Laravel Breeze felülettel és a Blade sablonokkal . Így a felhasználók regisztrálhatnak, hitelesíthetik magukat és feltölthetnek fájlokat a Supabase-re anélkül, hogy elhagynák a Laravel ökoszisztémát.

A vezérlőkön belül a Storage facade-et kellene használnod, amely a supabase lemezre mutat. Például egy űrlapról kapott fájl bemenettel rendelkező fájl feltöltéséhez valami ilyesmit tehetsz:

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

Ez a kód arra utasítja a Laravelt, hogy használja a Supabase lemezt , és helyezze a fájlt a konfigurált tároló virtuális feltöltési mappájába. Ha a kulcs és a végpont helyes, a fájl feltöltődik a Supabase tárolóba, és lekérheti az elérési útját, vagy nyilvános vagy aláírt URL-eket generálhat szabványos tárolási módszerekkel.

Ennek a megközelítésnek az az előnye, hogy az alkalmazás egyetlen felületet használ a tároláshoz, függetlenül attól, hogy helyi lemezt, Amazon S3-at, Supabase-t vagy más támogatott szolgáltatást használ. A szolgáltatóváltás a config/filesystems.php és a környezeti változók módosítására korlátozódik, az üzleti logika befolyásolása nélkül.

A Blade és Breeze kombinálásával feltöltési űrlapokat, fájllistákat és letöltési linkeket kínálhatsz, amelyek teljes mértékben integrálva vannak az alkalmazásod felhasználói élményébe. Továbbá a Supabase Storage tároló- és szabályzatalapú megközelítése lehetővé teszi, hogy kihasználd a hozzáférés-vezérlést és a biztonsági szabályokat annak meghatározásához, hogy mit tekinthet meg vagy tölthet le az egyes felhasználók.

Ez a csomagokból, illesztőprogramokból és konfigurációkból álló teljes ökoszisztéma lehetővé teszi a Laravel számára, hogy zökkenőmentesen működjön együtt a Supabase-szel, mind a Postgres relációs adatai, mind a fájltárolás, mind az UUID-kezelés tekintetében . A kulcsok, sémák és illesztőprogramok megfelelő konfigurálásával egy nagyon robusztus integrációt érhet el, amely elkerüli a két platform manuális összekapcsolásakor felmerülő számos tipikus hibát ezen támogató rétegek nélkül.

A Laravel és a Supabase összekapcsolása az adatbázis és a tárolás érdekében, a dedikált Supabase illesztőprogram kihasználása az UUID-k fejfájásmentes kezeléséhez, valamint a Flysystem adapter használata a tároláshoz lehetővé teszi modern alkalmazások létrehozását, ahol az összes összetett infrastruktúra a Laravel tiszta API-ja mögé van beágyazva, a migrációktól és a hitelesítéstől kezdve a fájlok biztonságos tárolókba való feltöltéséig.