Paano isama ang Supabase sa Laravel para sa database at imbakan

Informatec Digital » Kayamanan » Paano isama ang Supabase sa Laravel para sa database at imbakan

Kung gumagamit ka ng Laravel at nakatuon sa backend programming , at naghahanap ka ng paraan para lumipat sa isang moderno at pinamamahalaang PostgreSQL database tulad ng Supabase , malamang napagtanto mo na hindi sapat ang pagbabago lamang ng ilang variable sa .env file. May mga detalye ng koneksyon, mga schema, authentication, at pag-iimbak ng file na, kung hindi papansinin, ay maaaring humantong sa ilang medyo misteryosong mga error.

Bukod pa rito, kapag gusto mong gumawa ng mas malalim na hakbang at gamitin ang Supabase bilang imbakan ng file na isinama sa disk system (Storage) ng Laravel, medyo nagiging mas kumplikado ang mga bagay-bagay: mga service key, bucket, endpoint, custom na mga driver ng Flysystem, atbp. Ang magandang balita ay lahat ay maaaring perpektong maisama—ang database, imbakan, at paghawak ng UUID—sa isang medyo malinis na paraan.

Pagkonekta sa Laravel sa database ng Supabase

Ang unang hakbang ay ang pagkakaroon ng gumaganang proyekto sa Laravel at i-link ito sa database ng Postgres na ibinigay ng Supabase. Para dito, kailangan mo ng isang environment na may na-update na PHP at Composer , at maaari kang lumikha ng isang bagong proyekto o gumamit ng isang umiiral na. Mula sa console, buuin lamang ang proyekto gamit ang karaniwang utos ng Laravel at pagkatapos ay simulan ang pag-set up ng koneksyon.

Kapag naihanda mo na ang balangkas ng proyekto, ang karaniwang gawain ay ang pag-install ng isang simpleng sistema ng pagpapatotoo. Angkop na angkop ang Laravel Breeze dahil kasama rito ang mga template ng Blade at isang pangunahing proseso ng pag-login at pagpaparehistro , na nagbibigay-daan sa iyong mabilis na mapatunayan na ang koneksyon ng iyong database ay maayos na na-configure at maaari kang lumikha ng mga user nang walang problema.

Para makuha ang mga detalye ng koneksyon, mag-log in sa iyong Supabase dashboard at gumawa ng bagong proyekto sa database (magagawa mo ito nang direkta mula sa `database.new` , na magre-redirect sa wizard). Kung wala ka pang account, makikita mo muna ang sign-up screen; kung mayroon ka na, direktang pupunta ka sa mga setting ng proyekto at sa seksyon kung saan mo mahahanap ang connection string.

Sa loob ng pahina ng proyekto, sa seksyon ng koneksyon, makikita mo ang buton na "Kumonekta" o isang katulad nito. Ang pag-click dito ay magpapakita ng ilang format ng connection string (URI, mga indibidwal na parameter, atbp.). Kopyahin ang kumpletong URI, ngunit tandaan na palitan ang password gamit ang aktwal mong ginagamit para sa database, dahil madalas na ipinapakita ang default na password o placeholder.

Gamit ang impormasyong iyan, kailangan mong pumunta sa .env file ng iyong proyekto sa Laravel at i-update ang mga variable na DB_HOST, DB_PORT, DB_DATABASE, DB_USERNAME, at DB_PASSWORD, o i-configure ang variable na DATABASE_URL kung mas gusto mong gamitin ang buong format ng string. Ang layunin ay tiyaking ang lahat ay nakaturo sa Supabase Postgres cluster at hindi sa iyong localhost.

I-configure ang driver ng Postgres at ang schema ng Supabase sa Laravel

Sa Laravel, ang pangunahing file para sa configuration ng database ay config/database.php . Bagama't maaari mong direktang gamitin ang pgsql driver na kasama ng framework, kapag gumagamit ng Supabase, karaniwan ang paglalapat ng ilang karagdagang setting, lalo na tungkol sa mga schema at mga opsyon na partikular sa Postgres.

Ang isang tipikal na configuration ng Postgres sa Laravel ay maaaring magmukhang ganito, sa loob ng connections array, sa ilalim ng key na 'pgsql' :

'pgsql' => ,

Ang susi rito ay nasa parameter na `search_path` . Ang Supabase, bilang default, ay gumagamit ng `public` schema, na siyang ipinapakita sa pamamagitan ng mga API nito. Kung gusto mong panatilihing hiwalay ang iyong Laravel application mula sa schema na iyon at maiwasan ang mga conflict sa talahanayan o patakaran, lubos na inirerekomenda na baguhin ang `search_path` sa sarili mong schema, halimbawa, `laravel` , gaya ng nakita sa nakaraang halimbawa.

Sa ganitong paraan, ang mga migration at table na nabuo ng iyong proyekto ay malilikha sa alternatibong schema na ito at hindi sa publiko. Lubos na pinapasimple ng paghihiwalay na ito ang pamamahala ng mga panuntunan sa seguridad, RLS, at pag-access mula sa panel ng Supabase nang hindi pinapatungan ang anumang hindi mo dapat isulat, habang pinapanatiling organisado ang istruktura ng database.

Kapag naayos mo na ang configuration file, maaari mo nang patakbuhin ang mga migration gamit ang mga karaniwang command ng Laravel. Lilikha ito ng mga authentication table at anumang iba pang table na iyong tinukoy. Kung tama ang pagkakakonfigura ng lahat, awtomatikong tatakbo ang mga command laban sa Supabase Postgres server.

Kapag kumpleto na ang mga migration, simulan ang development server gamit ang `artisan serve` at subukang irehistro at i-log in ang mga user. Kung walang lumalabas na error sa koneksyon o migration, nangangahulugan ito na maayos ang komunikasyon ng Laravel sa Supabase at maaari mo nang ipagpatuloy ang pagbuo ng iyong business logic gaya ng dati.

Gamit ang isang partikular na driver ng Supabase sa Laravel

Bagama't gumagana ang karaniwang pgsql driver, mayroong isang pakete na nagdaragdag ng supabase database driver para sa Laravel , na nagpapalawak sa gawi ng PostgreSQL gamit ang mga kapaki-pakinabang na pagpapabuti, lalo na tungkol sa paghawak ng mga UUID column at sa paraan ng pagbuo ng mga query.

Ang paketeng ito, na ipinamamahagi bilang prahsys/laravel-supabase, ay naka-install sa pamamagitan ng Composer at nagrerehistro ng karagdagang driver na tinatawag na supabase na maaari mong gamitin sa iyong config/database.php file. Sa loob, ito ay batay sa Postgres driver ng Laravel, ngunit isinasama ang mga setting at grammar ng query na na-optimize para sa partikular na kapaligiran ng Supabase.

Kapag na-install na, maaari kang magdeklara ng katulad ng sumusunod sa loob ng seksyon ng mga koneksyon :

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

Ang bentahe ng paggamit ng driver na ito ay makukuha mo pa rin ang buong lakas ng Postgres engine, ngunit awtomatiko rin nitong pinangangasiwaan ang ilang maselang detalye ng Supabase, lalo na kapag gumagamit ng mga UUID bilang primary key o relationship field . Naiiwasan nito ang manu-manong pagsulat ng casting sa bawat kumplikadong query.

Ang pakete ay dinisenyo rin upang magkasya nang maayos sa mga modernong bersyon ng framework at PHP, na nag-aalok ng opisyal na pagiging tugma sa Laravel 10.x, 11.x at 12.x at sa PHP mula bersyon 8.1 pataas, pati na rin sa anumang karaniwang database ng PostgreSQL, kabilang siyempre ang Supabase.

Para matiyak na gumagana nang tama ang lahat, kasama sa package ang isang suite ng mga awtomatikong pagsubok. Maaari mong patakbuhin ang mga pagsubok gamit ang utos na `composer test`, na gagamit ng in-memory SQLite database para sa bilis, o maghanda ng `.env.testing` file na nakaturo sa iyong Supabase at patakbuhin ang `composer test-supabase` upang i-verify ang pag-uugali sa isang totoong kapaligiran gamit ang remote Postgres.

Pamamahala ng UUID sa Supabase at Laravel

May kakaibang katangian ang Supabase sa mga column ng UUID: kung susubukan mong ihambing ang isang UUID nang direkta sa isang text string nang hindi ginagamit ang query, maaaring mabigo ito o magbalik ng mga hindi inaasahang resulta . Sa isang bare Postgres environment, maaari mo itong malutas gamit ang mga global cast o custom operator, ngunit hindi pinapayagan ng Supabase ang mga ganitong global customization.

Ipinahihiwatig nito na ang isang direktang tanong ng estilo:

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

Hindi ito gagana gaya ng inaasahan mo. Gayunpaman, kung gagawin mo ang tahasang paghahagis:

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

Matagumpay ang query. Ang problema ay sa Laravel, kapag nagsusulat ka ng mga query gamit ang Eloquent o ang query builder, hindi mo gugustuhing magdagdag ng mga CAST sa bawat WHERE clause . Doon pumapasok ang supabase driver mula sa nabanggit na package, na siyang nagdadagdag ng mga cast na iyon para sa iyo.

Kapag aktibo ang driver na iyon, maaari kang magsagawa ng mga karaniwang query tulad ng:

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

At hindi lamang sa mga direktang query, kundi pati na rin sa mga join . Halimbawa, kung gusto mong kunin ang mga post at isama ang mga ito sa users table gamit ang isang UUID field, maaari mong gawin ang ganito:

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

Ang driver ay humahawak sa paglalapat ng mga kinakailangang text cast sa mga kaugnay na UUID column nang malinaw. Sa ganitong paraan, ang iyong code ay mananatiling idiomatic para sa Laravel, at hindi mo na kailangang magsulat ng raw SQL o gumamit ng mga kakaibang trick sa bawat kumplikadong query.

Kung gusto mo ng mas maayos na kontrol sa kung aling mga column ang maituturing na UUID, ang package ay nag-aalok ng CastsUuidColumns trait para sa iyong mga Eloquent model. Gamitin lang ito sa iyong model class at tukuyin ang isang protektadong array ng mga karagdagang column:

use Prahsys\Supabase\Traits\CastsUuidColumns;

class Post extends Model
{
    use CastsUuidColumns;

    protected $uuidColumns = ;
}

Ang katangiang ito ay may tatlong mahahalagang bagay na ginagawa: isinasama nito ang primary key bilang default na UUID, idinaragdag ang anumang mga column na iyong idedeklara sa property na `$uuidColumns` , at ipinapaalam ang impormasyong ito sa query builder upang malaman nito kung saan ilalapat ang mga cast. Ginagawa nitong pare-pareho at awtomatiko ang lahat ng pag-access sa data na kinasasangkutan ng mga UUID.

Para sa mas advanced na mga kaso , maaari kang magparehistro ng custom na UUID column detector. Gamit ang PostgresGrammar mula sa package, maaari kang tumukoy ng callback function na, batay sa pangalan ng column o konteksto ng query, ay magpapasya kung dapat ba itong ituring bilang isang UUID. Halimbawa:

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

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

Sa pamamagitan ng pag-set up ng function na ito, maaaring ituring ng system bilang UUID ang lahat ng column na ang pangalan ay may partikular na pattern o nasa loob ng isang partikular na listahan, na umaangkop sa mga partikular na kombensiyon sa pagpapangalan ng iyong proyekto.

Isama ang Supabase Storage bilang isang file system sa Laravel

Bukod sa database, maraming proyekto ang kailangang mag-imbak ng mga imahe, dokumento, o iba pang mga file na in-upload ng mga user. Kasama sa Supabase ang isang bucket-based storage service na maaari mong gamitin bilang disk ng Laravel sa pamamagitan ng Flysystem . May magagamit na isang partikular na adapter upang ituring ang Supabase Storage bilang karagdagang driver sa loob ng config/filesystems.php.

Ang paketeng pinag-uusapan ay nagbibigay ng isang Flysystem adapter na maayos na nakakapag-integrate sa Storage system ng framework. Natutugunan nito ang mga minimum na kinakailangan ng PHP >= 8.1, Laravel 10.x at 11.x , at ang PHP fileinfo extension (ext-fileinfo), na karaniwang inirerekomenda ng Laravel para sa paghawak ng file. Ginagawa ang pag-install gamit ang Composer, at kapag naisama na, kailangan mo lang tukuyin ang supabase disk sa configuration.

Sa config/filesystems.php file , sa loob ng disks array, magdaragdag ka ng katulad ng sumusunod:

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

Ang parameter na `bucket` ay karaniwang pangalan lamang ng storage bucket na iyong ginawa sa Supabase dashboard (halimbawa, `myapp-file-uploads`). Ang `endpoint` ay ang base URL ng storage service ng proyekto, na makikita rin sa kaukulang seksyon ng dashboard, at kadalasang hinango mula sa URL at rehiyon ng proyekto.

Ang opsyong `public` ay nagpapahiwatig kung ang mga nilalaman ng bucket ay ituturing na publiko bilang default. Kung `true`, ang adapter ay bubuo ng mga accessible na URL nang walang espesyal na lagda; kung `false`, ang opsyong `defaultUrlGeneration` ay gagana, na maaaring pilitin ang pagbuo ng mga nilagdaang URL na may oras ng pag-expire na tinukoy ng `signedUrlExpires`. Ang configuration na ito ay nagbibigay-daan sa iyong balansehin ang seguridad at kaginhawahan depende sa uri ng mga file na iyong hahawakan.

Karaniwang iniiwan bilang null ang pangkalahatang URL ng disk upang awtomatikong makuha ito ng adapter mula sa endpoint. Dapat mo lamang itong baguhin kung gumagamit ka ng intermediary proxy o CDN at gusto mong ituro ng mga nabuong ruta ang domain na iyon sa halip na sa native na Supabase domain.

I-troubleshoot ang mga error sa pag-upload at unawain ang susi sa Storage ng Supabase

Isang karaniwang problema kapag sinusubukang mag-upload ng mga file sa Supabase Storage mula sa Laravel ay ang pagtanggap ng mga mensahe tulad ng “Unable to write file at location: uploads/…” . Karaniwan itong nagpapahiwatig na, kahit na na-configure na ang driver, tinatanggihan ng Supabase ang write operation dahil sa hindi sapat na mga pahintulot o maling key configuration.

Sa supabase disk configuration file na `config/filesystems.php`, tinutukoy ng configuration ang paggamit ng "privileged key" sa `key` field, na tahasang nagsasaad na hindi gagana ang isang read-only key. Nangangahulugan ito na kailangan mong gumamit ng service key na may mga write permission sa bucket, hindi lamang isang client-side public API key o isang S3 compatibility key na walang mga permiso sa pagbabago.

Sa panel ng Supabase, sa loob ng seksyon ng API at storage configuration, makikita mo ang parehong anonymous keys at service_role keys (o ang mga katumbas nito) , na may mga extended privileges. Ang service key na ito, hindi ang public key, ang dapat mong ilagay sa SUPABASE_SECRET_ACCESS_KEY variable, na babasahin ng driver gamit ang env('SUPABASE_SECRET_ACCESS_KEY').

Kung sinusubukan mo gamit ang S3 key mula sa storage configuration o gamit ang mga generic API key ng proyekto, malamang na ang mga kredensyal na iyon ay walang mga pahintulot sa pagsusulat para sa partikular na bucket, na nagreresulta sa error sa pagsusulat. Ang pagpapalit ng value ng key sa isang valid service key na may mga pahintulot sa pagsusulat at pagkumpirma na umiiral ang bucket at wastong pinangalanan ay karaniwang nakakalutas sa isyu.

Bukod sa password, mahalagang beripikahin na ang bucket na tinukoy sa SUPABASE_STORAGE_BUCKET ay eksaktong tumutugma sa bucket na nilikha sa interface ng Supabase, na isinasaalang-alang ang malalaki at maliliit na titik, at na ang endpoint ay tumutugma sa tamang URL para sa storage instance na iyon. Ang isang detalye tulad ng dagdag na karakter o maling domain ay maaaring pumigil sa adapter na mahanap ang aktwal na destinasyon ng mga file.

Workflow na may Laravel Breeze, Blade, at Supabase Storage

Kapag na-configure mo na ang iyong database at storage, ang susunod na lohikal na hakbang ay ang pag-integrate ng lahat sa iyong Laravel Breeze interface at Blade templates . Sa ganitong paraan, maaaring magparehistro, mag-authenticate, at mag-upload ng mga file ang mga user sa Supabase nang hindi umaalis sa Laravel ecosystem.

Sa loob ng iyong mga controller, gagamitin mo ang Storage facade na nakaturo sa supabase disk. Halimbawa, para mag-upload ng file na natanggap mula sa isang form na may input ng file, maaari mong gawin ang ganito:

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

Sinasabi ng code na ito sa Laravel na gamitin ang Supabase disk at ilagay ang file sa loob ng virtual uploads folder sa loob ng na-configure na bucket. Kung tama ang key at endpoint, ia-upload ang file sa Supabase storage, at maaari mong kunin ang path nito o bumuo ng mga pampubliko o naka-sign na URL gamit ang mga karaniwang paraan ng storage.

Ang bentahe ng pamamaraang ito ay ang iyong aplikasyon ay nagpapanatili ng iisang interface para sa imbakan, gumagamit man ito ng lokal na disk, Amazon S3, Supabase, o iba pang sinusuportahang serbisyo. Ang pagpapalit ng mga provider ay nababawasan lamang sa pagsasaayos ng config/filesystems.php at mga environment variable, nang hindi naaapektuhan ang business logic.

Sa pamamagitan ng pagsasama nito sa Blade at Breeze, maaari kang mag-alok ng mga upload form, listahan ng file, at mga download link na ganap na isinama sa karanasan ng iyong application. Bukod pa rito, ang bucket- at policy-based na diskarte ng Supabase Storage ay nagbibigay-daan sa iyong gamitin ang mga kontrol sa pag-access at mga panuntunan sa seguridad nito upang tukuyin kung ano ang maaaring tingnan o i-download ng bawat user.

Ang buong ecosystem na ito ng mga package, driver, at configuration ay nagbibigay-daan sa Laravel na gumana nang maayos sa Supabase, kapwa sa mga tuntunin ng relational data gamit ang Postgres at file storage at pamamahala ng UUID . Sa pamamagitan ng wastong pag-configure ng mga key, schemas, at driver, makakamit mo ang isang napakatatag na integrasyon na nakakaiwas sa marami sa mga karaniwang error na nakatagpo kapag sinusubukang ikonekta ang parehong platform nang manu-mano nang walang mga sumusuportang layer na ito.

Ang pagkonekta sa Laravel sa Supabase para sa database at storage, paggamit ng nakalaang Supabase driver upang pamahalaan ang mga UUID nang walang sakit sa ulo, at paggamit ng Flysystem adapter para sa storage ay nagbibigay-daan sa iyong bumuo ng mga modernong aplikasyon kung saan ang lahat ng kumplikadong imprastraktura ay nakapaloob sa likod ng malinis na API ng Laravel, mula sa mga migrasyon at authentication hanggang sa pag-upload ng mga file at mga secure bucket.