Bagaimana untuk mengintegrasikan Supabase dengan Laravel untuk pangkalan data dan storan

Informatec Digital » Sumber » Cara mengintegrasikan Supabase dengan Laravel untuk pangkalan data dan storan

Jika anda bekerja dengan Laravel dan berdedikasi untuk pengaturcaraan backend , dan anda ingin membuat lompatan ke pangkalan data PostgreSQL moden yang diuruskan seperti Supabase , anda mungkin menyedari bahawa hanya menukar beberapa pembolehubah dalam fail .env tidak mencukupi. Terdapat butiran sambungan, skema, pengesahan dan storan fail yang, jika diabaikan, boleh menyebabkan beberapa ralat yang agak samar.

Tambahan pula, apabila anda ingin melangkah lebih jauh dan menggunakan Supabase sebagai storan fail yang disepadukan dengan sistem cakera Laravel (Storage), keadaan menjadi lebih rumit: kunci perkhidmatan, baldi, titik akhir, pemacu Flysystem tersuai, dan sebagainya. Berita baiknya ialah semuanya boleh disepadukan dengan sempurna—pangkalan data, storan dan pengendalian UUID—dengan cara yang agak bersih.

Menyambungkan Laravel ke pangkalan data Supabase

Langkah pertama adalah untuk mempunyai projek Laravel yang berfungsi dan memautkannya ke pangkalan data Postgres yang disediakan oleh Supabase. Untuk ini, anda memerlukan persekitaran dengan PHP dan Composer yang dikemas kini , dan anda boleh mencipta projek baharu atau menggunakan projek sedia ada. Dari konsol, hanya jana projek menggunakan arahan Laravel standard dan kemudian mula menyediakan sambungan.

Sebaik sahaja anda mempunyai rangka kerja projek, amalan biasa adalah memasang sistem pengesahan yang mudah. ​​Laravel Breeze sangat sesuai kerana ia merangkumi templat Blade dan aliran log masuk dan pendaftaran asas , yang membolehkan anda mengesahkan dengan cepat bahawa sambungan pangkalan data anda dikonfigurasikan dengan betul dan anda boleh mencipta pengguna tanpa masalah.

Untuk mendapatkan butiran sambungan, log masuk ke papan pemuka Supabase anda dan cipta projek pangkalan data baharu (anda boleh melakukannya terus daripada `database.new` , yang akan mengalihkannya ke wizard). Jika anda belum mempunyai akaun, anda akan melihat skrin pendaftaran terlebih dahulu; jika anda sudah mempunyai akaun, anda akan terus ke tetapan projek dan bahagian tempat anda boleh menemui rentetan sambungan.

Dalam halaman projek, di bahagian sambungan, anda akan menemui butang "Sambung" atau sesuatu yang serupa. Mengkliknya akan memaparkan beberapa format rentetan sambungan (URI, parameter individu, dll.). Salin URI lengkap, tetapi ingat untuk menggantikan kata laluan dengan kata laluan yang sebenarnya anda gunakan untuk pangkalan data, kerana kata laluan atau ruang letak lalai sering dipaparkan.

Dengan maklumat tersebut, anda perlu pergi ke fail .env projek Laravel anda dan kemas kini pembolehubah DB_HOST, DB_PORT, DB_DATABASE, DB_USERNAME dan DB_PASSWORD, atau konfigurasikan pembolehubah DATABASE_URL jika anda lebih suka menggunakan format rentetan penuh. Matlamatnya adalah untuk memastikan semuanya menghala ke kluster Supabase Postgres dan bukan ke localhost anda.

Konfigurasikan pemacu Postgres dan skema Supabase dalam Laravel

Dalam Laravel, fail utama untuk konfigurasi pangkalan data ialah config/database.php . Walaupun anda boleh menggunakan pemacu pgsql yang disertakan dengan rangka kerja secara langsung, apabila bekerja dengan Supabase, adalah perkara biasa untuk menggunakan beberapa tetapan tambahan, terutamanya mengenai skema dan pilihan khusus Postgres.

Konfigurasi Postgres biasa dalam Laravel mungkin kelihatan seperti ini, dalam array sambungan, di bawah kekunci 'pgsql' :

'pgsql' => ,

Kuncinya di sini terletak pada parameter `search_path` . Supabase, secara lalai, menggunakan skema `public`, iaitu skema yang didedahkan melalui APInya. Jika anda ingin memastikan aplikasi Laravel anda berasingan daripada skema tersebut dan mengelakkan konflik jadual atau dasar, adalah sangat disyorkan untuk menukar `search_path` kepada skema anda sendiri, contohnya, `laravel` , seperti yang dilihat dalam contoh sebelumnya.

Dengan cara ini, migrasi dan jadual yang dijana oleh projek anda akan dicipta dalam skema alternatif ini dan bukan di khalayak ramai. Pemisahan ini sangat memudahkan pengurusan peraturan keselamatan, RLS dan akses daripada panel Supabase tanpa menulis ganti apa-apa yang tidak sepatutnya, sambil mengekalkan struktur pangkalan data yang teratur.

Sebaik sahaja anda melaraskan fail konfigurasi, anda boleh menjalankan migrasi menggunakan arahan Laravel standard. Ini akan mencipta jadual pengesahan dan sebarang jadual lain yang telah anda tentukan. Jika semuanya dikonfigurasikan dengan betul, arahan akan dijalankan terhadap pelayan Supabase Postgres secara automatik.

Setelah migrasi selesai, mulakan pelayan pembangunan dengan `artisan serve` dan cuba daftar dan log masuk pengguna. Jika tiada ralat sambungan atau migrasi muncul, ini bermakna Laravel berkomunikasi dengan betul dengan Supabase dan anda boleh terus membina logik perniagaan anda seperti biasa.

Menggunakan pemacu Supabase tertentu dalam Laravel

Walaupun pemacu pgsql standard berfungsi, terdapat pakej yang menambah pemacu pangkalan data supabase untuk Laravel , yang melanjutkan tingkah laku PostgreSQL dengan penambahbaikan yang sangat berguna, terutamanya mengenai pengendalian lajur UUID dan cara pertanyaan dibina.

Pakej ini, yang diedarkan sebagai prahsys/laravel-supabase, dipasang melalui Composer dan mendaftarkan pemacu tambahan yang dipanggil supabase yang boleh anda gunakan dalam fail config/database.php anda. Secara dalaman, ia berdasarkan pemacu Postgres Laravel, tetapi menggabungkan tetapan dan tatabahasa pertanyaan yang dioptimumkan untuk persekitaran Supabase tertentu.

Setelah dipasang, anda boleh mengisytiharkan sesuatu seperti berikut dalam bahagian sambungan :

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

Kelebihan menggunakan pemacu ini ialah anda masih mendapat kuasa penuh enjin Postgres, tetapi ia juga mengendalikan butiran Supabase tertentu secara automatik, terutamanya apabila bekerja dengan UUID sebagai kunci utama atau medan perhubungan . Ini mengelakkan daripada perlu menulis pemutus secara manual dalam setiap pertanyaan yang kompleks.

Pakej ini juga direka bentuk agar sesuai dengan versi moden rangka kerja dan PHP, menawarkan keserasian rasmi dengan Laravel 10.x, 11.x dan 12.x dan dengan PHP dari versi 8.1 dan seterusnya, serta mana-mana pangkalan data PostgreSQL standard, termasuk sudah tentu Supabase.

Untuk memastikan semuanya berfungsi dengan betul, pakej ini merangkumi satu set ujian automatik. Anda boleh menjalankan ujian dengan arahan `composer test`, yang akan menggunakan pangkalan data SQLite dalam memori untuk kelajuan, atau menyediakan fail `.env.testing` yang menghala ke Supabase anda dan menjalankan `composer test-supabase` untuk mengesahkan tingkah laku dalam persekitaran dunia sebenar dengan Postgres jauh.

Pengurusan UUID dalam Supabase dan Laravel

Supabase mempunyai keanehan dengan lajur UUID: jika anda cuba membandingkan UUID secara langsung dengan rentetan teks tanpa menghantar, pertanyaan mungkin gagal atau mengembalikan hasil yang tidak dijangka . Dalam persekitaran Postgres kosong, anda boleh menyelesaikannya dengan penghantaran global atau operator tersuai, tetapi Supabase tidak membenarkan penyesuaian global sedemikian.

Ini menunjukkan bahawa pertanyaan langsung gaya:

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

Ia tidak akan berfungsi seperti yang anda jangkakan. Walau bagaimanapun, jika anda melakukan pemilihan pelakon eksplisit:

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

Pertanyaan berjaya. Masalahnya ialah dalam Laravel, apabila anda menulis pertanyaan dengan Eloquent atau pembina pertanyaan, anda tidak mahu menambah CAST pada setiap klausa WHERE . Di situlah pemacu supabase daripada pakej yang dinyatakan di atas digunakan, yang menambah cetakan tersebut untuk anda.

Dengan pemacu itu aktif, anda boleh melakukan pertanyaan biasa seperti:

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

Dan bukan sahaja dalam pertanyaan langsung, tetapi juga dalam gabungan . Contohnya, jika anda ingin mendapatkan semula siaran dan menggabungkannya dengan jadual pengguna menggunakan medan UUID, anda boleh melakukan sesuatu seperti ini:

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

Pemacu mengendalikan penggunaan teks yang diperlukan pada lajur UUID yang berkaitan secara telus. Dengan cara ini, kod anda kekal idiomatik untuk Laravel, dan anda tidak perlu menulis SQL mentah atau menggunakan helah pelik dalam setiap pertanyaan yang kompleks.

Jika anda mahukan kawalan yang lebih baik ke atas lajur mana yang dianggap sebagai UUID, pakej ini menawarkan ciri CastsUuidColumns untuk model Eloquent anda. Hanya gunakannya dalam kelas model anda dan tentukan tatasusunan lajur tambahan yang dilindungi:

use Prahsys\Supabase\Traits\CastsUuidColumns;

class Post extends Model
{
    use CastsUuidColumns;

    protected $uuidColumns = ;
}

Ciri ini melakukan tiga perkara penting: ia memasukkan kunci utama sebagai UUID lalai, menambah sebarang lajur yang anda isytiharkan pada sifat `$uuidColumns` dan menyampaikan maklumat ini kepada pembina pertanyaan supaya ia tahu di mana hendak menggunakan cetakan. Ini menjadikan semua akses data yang melibatkan UUID konsisten dan automatik.

Untuk kes yang lebih lanjut , anda boleh mendaftarkan pengesan lajur UUID tersuai. Menggunakan PostgresGrammar daripada pakej, anda boleh menentukan fungsi panggil balik yang, berdasarkan nama lajur atau konteks pertanyaan, memutuskan sama ada ia harus dianggap sebagai UUID. Contohnya:

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

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

Dengan fungsi ini disediakan, sistem boleh mempertimbangkan semua lajur yang namanya mempunyai corak tertentu atau berada dalam senarai tertentu sebagai UUID, menyesuaikan diri dengan konvensyen penamaan yang sangat spesifik bagi projek anda.

Integrasikan Storan Supabase sebagai sistem fail dalam Laravel

Selain pangkalan data, banyak projek perlu menyimpan imej, dokumen atau fail lain yang dimuat naik oleh pengguna. Supabase termasuk perkhidmatan storan berasaskan baldi yang boleh anda gunakan sebagai cakera Laravel melalui Flysystem . Penyesuai khusus tersedia untuk melayan Supabase Storage sebagai pemacu tambahan dalam config/filesystems.php.

Pakej yang dimaksudkan menyediakan penyesuai Flysystem yang berintegrasi dengan lancar dengan sistem Storan rangka kerja. Ia memenuhi keperluan minimum PHP >= 8.1, Laravel 10.x dan 11.x , dan sambungan failinfo PHP (ext-fileinfo), yang biasanya disyorkan oleh Laravel untuk pengendalian fail. Pemasangan dilakukan menggunakan Composer, dan setelah disertakan, anda hanya perlu menentukan cakera supabase dalam konfigurasi.

Dalam fail config/filesystems.php , dalam tatasusunan cakera, anda akan menambah sesuatu yang serupa dengan yang berikut:

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

Parameter `baldi` biasanya hanyalah nama baldi storan yang anda cipta dalam papan pemuka Supabase (contohnya, `myapp-file-uploads`). `Endpoint` ialah URL asas perkhidmatan storan projek, juga boleh dilihat dalam bahagian papan pemuka yang sepadan dan biasanya diperoleh daripada URL dan rantau projek.

Pilihan `awam` menunjukkan sama ada kandungan baldi akan dianggap sebagai awam secara lalai. Jika `benar`, penyesuai akan menjana URL yang boleh diakses tanpa tandatangan khas; jika `palsu`, pilihan `defaultUrlGeneration` akan dimainkan, yang boleh memaksa penjanaan URL yang ditandatangani dengan masa tamat tempoh yang ditentukan oleh `signedUrlExpires`. Konfigurasi ini membolehkan anda mengimbangi keselamatan dan kemudahan bergantung pada jenis fail yang anda kendalikan.

URL cakera umum biasanya dibiarkan sebagai nol supaya penyesuai secara automatik memperolehnya daripada titik akhir. Anda hanya perlu mengubahnya jika anda menggunakan proksi perantara atau CDN dan mahu laluan yang dijana menghala ke domain tersebut dan bukannya domain Supabase asli.

Selesaikan masalah ralat muat naik dan fahami kunci kepada Storan Supabase

Masalah yang agak biasa apabila cuba memuat naik fail ke Supabase Storage daripada Laravel ialah menerima mesej seperti “Tidak dapat menulis fail di lokasi: muat naik/…” . Ini biasanya menunjukkan bahawa, walaupun pemacu telah dikonfigurasikan, Supabase menolak operasi penulisan disebabkan oleh kebenaran yang tidak mencukupi atau konfigurasi kekunci yang salah.

Dalam fail konfigurasi cakera supabase, `config/filesystems.php`, konfigurasi tersebut menentukan penggunaan "kunci istimewa" dalam medan `kunci`, yang menyatakan secara eksplisit bahawa kunci baca sahaja tidak akan berfungsi. Ini bermakna anda perlu menggunakan kunci perkhidmatan dengan kebenaran menulis ke baldi, bukan sekadar kunci API awam bahagian klien atau kunci keserasian S3 tanpa kebenaran pengubahsuaian.

Dalam panel Supabase, dalam bahagian konfigurasi API dan storan, anda akan menemui kedua-dua kekunci tanpa nama dan kekunci service_role (atau yang setaraf dengannya) , yang mempunyai keistimewaan lanjutan. Kekunci perkhidmatan inilah, bukan kekunci awam, yang harus anda letakkan dalam pembolehubah SUPABASE_SECRET_ACCESS_KEY, yang kemudiannya akan dibaca oleh pemacu menggunakan env('SUPABASE_SECRET_ACCESS_KEY').

Jika anda telah menguji dengan kunci S3 daripada konfigurasi storan atau dengan kunci API generik projek, kemungkinan besar kelayakan tersebut tidak mempunyai kebenaran tulis pada baldi tertentu, mengakibatkan ralat tulis. Menukar nilai kunci kepada kunci perkhidmatan yang sah dengan kebenaran tulis dan mengesahkan bahawa baldi itu wujud dan dinamakan dengan betul biasanya menyelesaikan masalah tersebut.

Selain kata laluan, adalah penting untuk mengesahkan bahawa baldi yang ditakrifkan dalam SUPABASE_STORAGE_BUCKET sepadan dengan yang dicipta dalam antara muka Supabase, dengan menghormati huruf besar dan kecil, dan titik akhir sepadan dengan URL yang betul untuk tika storan tersebut. Butiran seperti aksara tambahan atau domain yang salah boleh menghalang penyesuai daripada mencari destinasi sebenar fail.

Aliran kerja dengan Laravel Breeze, Blade dan Storan Supabase

Sebaik sahaja pangkalan data dan storan anda dikonfigurasikan, langkah logik seterusnya adalah untuk mengintegrasikan semuanya dengan antara muka Laravel Breeze dan templat Blade anda . Dengan cara ini, pengguna boleh mendaftar, mengesahkan dan memuat naik fail ke Supabase tanpa meninggalkan ekosistem Laravel.

Dalam pengawal anda, anda akan menggunakan fasad Storage yang menghala ke cakera supabase. Contohnya, untuk memuat naik fail yang diterima daripada borang dengan input fail, anda boleh melakukan sesuatu seperti ini:

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

Kod ini memberitahu Laravel untuk menggunakan cakera Supabase dan meletakkan fail di dalam folder muat naik maya dalam baldi yang dikonfigurasikan. Jika kunci dan titik akhir betul, fail tersebut akan dimuat naik ke storan Supabase dan anda boleh mendapatkan semula laluannya atau menjana URL awam atau bertandatangan menggunakan kaedah storan standard.

Kelebihan pendekatan ini ialah aplikasi anda mengekalkan antara muka tunggal untuk storan, tidak kira sama ada ia menggunakan cakera setempat, Amazon S3, Supabase atau perkhidmatan lain yang disokong. Penukaran pembekal dikurangkan kepada melaraskan config/filesystems.php dan pembolehubah persekitaran, tanpa menjejaskan logik perniagaan.

Dengan menggabungkannya dengan Blade dan Breeze, anda boleh menawarkan borang muat naik, senarai fail dan pautan muat turun yang disepadukan sepenuhnya ke dalam pengalaman pengguna aplikasi anda. Tambahan pula, pendekatan berasaskan baldi dan dasar Supabase Storage membolehkan anda memanfaatkan kawalan akses dan peraturan keselamatannya untuk menentukan apa yang boleh dilihat atau dimuat turun oleh setiap pengguna.

Keseluruhan ekosistem pakej, pemacu dan konfigurasi ini membolehkan Laravel berfungsi dengan lancar dengan Supabase, baik dari segi data hubungan dengan Postgres mahupun penyimpanan fail dan pengurusan UUID . Dengan mengkonfigurasi kekunci, skema dan pemacu dengan betul, anda mencapai integrasi yang sangat mantap yang mengelakkan banyak ralat biasa yang dihadapi apabila cuba menyambungkan kedua-dua platform secara manual tanpa lapisan sokongan ini.

Menghubungkan Laravel dengan Supabase untuk pangkalan data dan storan, memanfaatkan pemacu Supabase khusus untuk mengurus UUID tanpa masalah, dan menggunakan penyesuai Flysystem untuk storan membolehkan anda membina aplikasi moden di mana semua infrastruktur kompleks dirangkumkan di sebalik API bersih Laravel, daripada migrasi dan pengesahan kepada memuat naik fail kepada baldi selamat.