Cara mengintegrasikan Supabase dengan Laravel untuk database dan penyimpanan

Informatec Digital » Sumber daya » Cara mengintegrasikan Supabase dengan Laravel untuk database dan penyimpanan

Jika Anda bekerja dengan Laravel dan berdedikasi pada pemrograman backend dan Anda merasa ingin melakukan lompatan ke database Supabase seperti PostgreSQL modern dan terkelolaAnda mungkin menyadari bahwa hanya mengubah beberapa variabel dalam file .env saja tidak cukup. Ada detail koneksi, skema, autentikasi, dan penyimpanan file yang, jika diabaikan, dapat menyebabkan beberapa kesalahan yang agak samar.

Selain itu, ketika Anda ingin melangkah lebih jauh dan menggunakan Supabase sebagai penyimpanan file Ketika terintegrasi dengan sistem penyimpanan Laravel, semuanya menjadi sedikit lebih kompleks: kunci layanan, bucket, titik akhir, driver Flysystem khusus, dll. Kabar baiknya adalah semuanya—database, penyimpanan, dan penanganan UUID—dapat diintegrasikan dengan sempurna dan cukup rapi.

Menghubungkan Laravel ke database Supabase

Langkah pertama adalah memiliki proyek Laravel yang berfungsi dan menautkannya ke database Postgres yang disediakan oleh Supabase. Untuk ini, Anda memerlukan lingkungan dengan PHP dan Composer diperbarui dan buat proyek baru atau gunakan proyek yang sudah ada. Dari konsol, cukup buat proyek dengan perintah Laravel standar, lalu mulai atur koneksinya.

Setelah Anda memiliki kerangka proyek, langkah yang biasa dilakukan adalah memasang sistem autentikasi sederhana. Laravel Breeze sangat cocok karena mencakup: Templat bilah dan alur login dan registrasi dasarIni memungkinkan Anda dengan cepat memverifikasi bahwa koneksi basis data Anda dikonfigurasi dengan benar dan Anda dapat membuat pengguna tanpa masalah.

Untuk mendapatkan detail koneksi, masuk ke panel Supabase Anda dan buat proyek database baru (Anda dapat melakukannya langsung dari database.baru(yang akan mengarahkan Anda ke wizard). Jika Anda belum memiliki akun, Anda akan melihat layar pendaftaran terlebih dahulu; jika sudah memiliki akun, Anda akan langsung masuk ke pengaturan proyek dan bagian tempat Anda dapat memeriksa string koneksi.

Di dalam halaman proyek, di bagian koneksi, Anda akan menemukan tombol seperti "Connect" atau serupa. Saat Anda mengkliknya, Supabase akan menampilkan beberapa format string koneksi (URI, parameter individual, dll.). Salin URI lengkapnya, tetapi ingat bahwa Anda harus ganti kata sandinya untuk yang benar-benar Anda gunakan dalam basis data, karena yang default atau placeholder sering kali ditampilkan.

Dengan informasi tersebut, Anda perlu membuka berkas .env proyek Laravel Anda dan memperbarui variabel DB_HOST, DB_PORT, DB_DATABASE, DB_USERNAME, dan DB_PASSWORD, atau mengonfigurasi variabel DATABASE_URL jika Anda ingin menggunakan format string lengkap. Tujuannya adalah agar semuanya mengarah ke Kluster Postgres Supabase dan tidak ke localhost Anda.

Konfigurasikan driver Postgres dan skema Supabase di Laravel

Di Laravel, file kunci untuk konfigurasi database adalah konfigurasi/database.phpMeskipun Anda dapat langsung menggunakan driver pgsql yang disertakan dalam kerangka kerja, saat bekerja dengan Supabase, biasanya akan diterapkan beberapa penyesuaian tambahan, khususnya terkait skema dan opsi khusus Postgres.

Konfigurasi khas untuk Postgres di Laravel mungkin terlihat seperti ini, dalam array koneksi, di bawah kunci 'pgsql':

'pgsql' => ,

Kuncinya di sini ada pada parameternya jalur_pencarianSupabase, secara default, menggunakan skema publik, yang diekspos melalui API-nya. Jika Anda ingin aplikasi Laravel Anda terpisah dari skema tersebut dan menghindari konflik tabel atau kebijakan, sangat disarankan untuk mengubah search_path ke skema Anda sendiri, misalnya. LARAVEL, seperti yang terlihat pada contoh sebelumnya.

Dengan cara ini, migrasi dan tabel yang dihasilkan oleh proyek Anda akan dibuat dalam skema alternatif tersebut, bukan di publik. Pemisahan ini akan sangat memudahkan pengelolaan. aturan keamanan, RLS dan akses dari panel Supabase tanpa menginjak apa pun yang tidak seharusnya dan menjaga struktur basis data tetap terorganisir.

Setelah Anda menyesuaikan berkas konfigurasi, Anda dapat memulai migrasi menggunakan perintah Laravel yang biasa. Ini akan membuat tabel autentikasi dan tabel lain yang telah Anda definisikan. Jika semuanya dikonfigurasi dengan benar, perintah akan dijalankan terhadap Supabase Postgres tanpa Anda harus melakukan hal lainnya.

Setelah migrasi selesai, jalankan server pengembangan dengan 'artisan serve' dan coba daftarkan serta login pengguna. Jika tidak ada kesalahan koneksi atau migrasi yang muncul, artinya Laravel berfungsi. berkomunikasi dengan benar dengan Supabase dan kamu bisa terus membangun logika bisnis Anda biasanya.

Menggunakan driver Supabase tertentu di Laravel

Meskipun driver pgsql standar berfungsi, ada paket yang menambahkan driver database supabase untuk Laravel, memperluas perilaku PostgreSQL dengan penyempurnaan yang sangat berguna, terutama mengenai penanganan kolom UUID dan cara kueri dibangun.

Paket ini, didistribusikan sebagai prahsys/laravel-supabase, diinstal melalui Composer dan mendaftarkan driver tambahan bernama supabase yang dapat Anda gunakan di berkas config/database.php. Secara internal, paket ini berbasis driver Postgres Laravel, tetapi menggabungkan pengaturan dan tata bahasa pencarian dioptimalkan untuk lingkungan Supabase tertentu.

Setelah terinstal, Anda dapat mendeklarasikan sesuatu seperti berikut di dalam bagian koneksi:

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

Keuntungan menggunakan driver ini adalah Anda masih mendapatkan semua kekuatan mesin Postgres, tetapi juga secara otomatis menangani detail halus tertentu dari Supabase, terutama saat bekerja dengan UUID sebagai kunci utama atau bidang hubunganHal ini menghindari keharusan menulis casting secara manual untuk setiap query yang rumit.

Paket ini juga dirancang agar sesuai dengan versi modern dari framework dan PHP, menawarkan kompatibilitas resmi dengan Laravel 10.x, 11.x, 12.x dan dengan PHP mulai versi 8.1 dan seterusnya, serta semua basis data PostgreSQL standar, termasuk tentu saja Supabase.

Untuk memastikan semuanya berfungsi dengan benar, paket ini menyertakan serangkaian pengujian otomatis. Anda dapat menjalankan pengujian dengan perintah `composer test`, yang akan menggunakan database SQLite dalam memori untuk kecepatan, atau menyiapkan berkas `.env.testing` yang mengarah ke Supabase Anda dan menjalankan `composer test-supabase` untuk memverifikasi perilaku di lingkungan nyata. Postgres Jarak Jauh.

Manajemen UUID di Supabase dan Laravel

Supabase memiliki kekhasan dengan kolom UUID: jika Anda mencoba membandingkan UUID secara langsung dengan string teks tanpa casting, kueri mungkin gagal atau mengembalikan hasil yang tidak diharapkanDalam sistem Postgres "biasa" Anda dapat menyelesaikan ini dengan pemeran global atau operator khusus, tetapi dalam Supabase kustomisasi global ini tidak diperbolehkan.

Ini menyiratkan daripada penyelidikan langsung terhadap gaya:

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

Itu tidak akan berhasil Seperti yang Anda harapkan. Namun, jika Anda melakukan casting eksplisit:

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

Query berhasil. Masalahnya adalah di Laravel, ketika Anda menulis query dengan Eloquent atau query builder, Anda tidak ingin pergi menempatkan CAST di setiap tempatDi sinilah driver supabase dari paket yang disebutkan sebelumnya berperan, yang mengurus penambahan gips tersebut untuk Anda.

Dengan driver yang aktif, Anda dapat melakukan pertanyaan umum sebagai:

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

Dan tidak hanya dalam konsultasi langsung, tetapi juga dalam bergabungMisalnya, jika Anda ingin mengambil postingan dan menggabungkannya dengan tabel pengguna menggunakan bidang UUID, Anda dapat melakukan sesuatu seperti ini:

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

Pengemudi bertanggung jawab untuk menerapkan pemeran yang dibutuhkan untuk teks di kolom UUID yang relevan, secara transparan. Dengan cara ini, kode Anda tetap idiomatis untuk Laravel, dan Anda tidak perlu menulis SQL mentah atau menggunakan trik aneh di setiap kueri yang rumit.

Jika Anda menginginkan kontrol yang lebih baik atas kolom mana yang dianggap UUID, paket ini menawarkan sifat CastsUuidColumns untuk model Eloquent Anda. Cukup gunakan di kelas model dan tentukan array terproteksi dari kolom tambahan:

use Prahsys\Supabase\Traits\CastsUuidColumns;

class Post extends Model
{
    use CastsUuidColumns;

    protected $uuidColumns = ;
}

Sifat ini melakukan tiga hal penting: ia menyertakan kunci utama sebagai UUID secara default, dan ia menambahkan kolom apa pun yang Anda deklarasikan dalam properti. Kolom $uuid dan mengomunikasikan informasi tersebut ke pembuat kueri agar tahu di mana harus menerapkan cast. Dengan demikian, semua akses data yang melibatkan UUID menjadi konsisten dan otomatis.

Untuk kasus yang lebih parahAnda dapat mendaftarkan detektor kolom UUID kustom. Dengan menggunakan paket PostgresGrammar, Anda dapat menentukan fungsi panggilan balik yang, berdasarkan nama kolom atau konteks kueri, akan memutuskan apakah kolom tersebut harus diperlakukan sebagai UUID. Misalnya:

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

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

Dengan fungsi ini yang telah ditetapkan, sistem dapat mempertimbangkan semua kolom yang namanya memiliki pola tertentu atau berada dalam daftar tertentu sebagai UUID, beradaptasi dengan konvensi penamaan yang sangat spesifik proyek Anda.

Integrasikan Supabase Storage sebagai sistem file di Laravel

Selain database, banyak proyek perlu menyimpan gambar, dokumen, atau berkas lain yang diunggah oleh pengguna. Supabase menyediakan layanan penyimpanan berbasis bucket yang dapat Anda manfaatkan sebagai berikut: Disk Laravel menggunakan FlysystemUntuk tujuan ini, ada adaptor khusus yang memungkinkan Supabase Storage diperlakukan sebagai driver lain dalam config/filesystems.php.

Paket yang dimaksud menyediakan adaptor Flysystem yang terintegrasi secara transparan dengan sistem Penyimpanan kerangka kerja. Adaptor ini memenuhi persyaratan minimum PHP >= 8.1, Laravel 10.x atau 11.x dan ekstensi fileinfo PHP (ext-fileinfo), yang sudah direkomendasikan Laravel untuk menangani berkas. Instalasi dilakukan dengan Composer, dan setelah disertakan, Anda hanya perlu menentukan disk supabase dalam konfigurasi.

Di File konfigurasi/sistem berkas.phpDi dalam disk array, Anda akan menambahkan sesuatu yang mirip dengan berikut ini:

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

Parameter bucket biasanya hanya berupa nama ember penyimpanan yang Anda buat di panel Supabase (misalnya, myapp-file-uploads). Titik akhir adalah URL dasar layanan penyimpanan proyek, yang juga terlihat di bagian panel yang sesuai, dan biasanya berasal dari URL dan wilayah proyek.

Opsi `public` menunjukkan apakah isi bucket akan diperlakukan sebagai publik secara default. Jika `true`, adaptor akan menghasilkan URL yang dapat diakses tanpa tanda tangan khusus; jika `false`, opsi `defaultUrlGeneration` akan aktif, yang dapat memaksa pembuatan URL yang ditandatangani dengan waktu kedaluwarsa yang ditentukan oleh `signedUrlExpires`. Konfigurasi ini memungkinkan Anda untuk menyeimbangkan beban. keamanan dan kenyamanan tergantung pada jenis berkas yang Anda tangani.

URL disk umum biasanya dibiarkan kosong agar adaptor dapat secara otomatis mengambilnya dari titik akhir. Anda hanya boleh menyentuhnya jika Anda menggunakan proxy atau CDN perantara dan Anda ingin rute yang dihasilkan menunjuk ke domain tersebut, bukan domain Supabase asli.

Pecahkan masalah kesalahan unggahan dan pahami kunci Supabase Storage

Masalah yang cukup umum ketika mencoba mengunggah file ke Supabase Storage dari Laravel adalah menerima pesan seperti “Tidak dapat menulis file di lokasi: uploads/…”Ini biasanya menunjukkan bahwa, meskipun driver dikonfigurasi, Supabase menolak operasi penulisan karena izin tidak mencukupi atau kunci salah konfigurasi.

Di disk supabase config/filesystems.php, konfigurasi menyebutkan penggunaan "kunci istimewa" di kolom kunci, yang secara eksplisit menyatakan bahwa kunci baca-saja tidak akan berfungsi. Ini berarti Anda perlu menggunakan kunci layanan yang memiliki izin menulis pada bucket, bukan sekadar kunci API publik yang ditujukan untuk klien atau kunci yang ditujukan untuk kompatibilitas S3 tanpa izin modifikasi.

Di panel Supabase, di dalam bagian konfigurasi API dan penyimpanan, Anda akan menemukan kunci anonim dan service_role atau setaraIni adalah yang memiliki hak akses yang diperluas. Kunci layanan itulah, dan bukan yang publik, yang harus Anda tempatkan di variabel SUPABASE_SECRET_ACCESS_KEY, yang kemudian akan dibaca oleh driver melalui env('SUPABASE_SECRET_ACCESS_KEY').

Jika Anda telah menguji dengan kunci S3 dari konfigurasi penyimpanan atau dengan kunci API generik dari proyek, kemungkinan besar kredensial tersebut tidak memiliki izin untuk menulis ke bucket tertentu, yang mengakibatkan kesalahan penulisan. Mengubah nilai kunci menjadi kunci layanan yang valid dengan izin menulis Dan dengan mengonfirmasi bahwa bucket tersebut ada dan ditulis dengan benar, masalah biasanya terpecahkan.

Selain kunci, penting untuk memverifikasi bahwa bucket yang didefinisikan dalam SUPABASE_STORAGE_BUCKET sama persis dengan bucket yang dibuat di antarmuka Supabase, dengan memperhatikan huruf besar dan kecil, dan bahwa titik akhir sesuai dengan URL yang benar untuk instans penyimpanan tersebut. Detail seperti karakter tambahan atau domain yang salah dapat mencegah adaptor berfungsi. temukan tujuan sebenarnya dari file tersebut.

Alur Kerja dengan Laravel Breeze, Blade, dan Supabase Storage

Setelah Anda menyiapkan database dan penyimpanan, langkah alami berikutnya adalah mengintegrasikan semuanya dengan Antarmuka Laravel Breeze dan template BladeDengan cara ini, pengguna dapat mendaftar, mengautentikasi, dan mengunggah file ke Supabase tanpa meninggalkan ekosistem Laravel.

Di dalam pengontrol Anda, Anda akan menggunakan Fasad penyimpanan menunjuk ke disk supabase. Misalnya, untuk mengunggah berkas yang diterima dari formulir dengan input berkas, Anda dapat melakukan hal berikut:

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

Kode ini memberi tahu Laravel untuk menggunakan disk supabase dan letakkan berkas di dalam folder unggahan virtual di dalam bucket yang telah dikonfigurasi. Jika kunci dan titik akhir sudah benar, berkas akan diunggah ke penyimpanan Supabase, dan Anda dapat mengambil jalurnya atau membuat URL publik atau bertanda tangan menggunakan metode penyimpanan standar.

Keuntungan dari pendekatan ini adalah aplikasi Anda mempertahankan satu antarmuka untuk penyimpanan, terlepas dari apakah aplikasi tersebut menggunakan disk lokal, Amazon S3, Supabase, atau layanan pendukung lainnya. Perpindahan penyedia layanan hanya perlu dilakukan sesuaikan config/filesystems.php dan variabel lingkungan, tanpa menyentuh logika bisnis.

Dengan menggabungkan ini dengan Blade dan Breeze, Anda dapat menawarkan formulir unggah, daftar berkas, dan tautan unduhan yang terintegrasi sepenuhnya ke dalam pengalaman pengguna aplikasi Anda. Lebih lanjut, pendekatan berbasis bucket dan kebijakan Supabase Storage memungkinkan Anda memanfaatkan kontrol akses dan aturan keamanan untuk menentukan apa yang dapat dilihat atau diunduh setiap pengguna.

Seluruh ekosistem paket, driver, dan konfigurasi ini memungkinkan Laravel bekerja dengan sangat nyaman dengan Supabase, baik dalam aspek data relasional dengan Postgres maupun dalam... penyimpanan file dan manajemen UUIDDengan menyesuaikan kunci, skema, dan driver dengan tepat, Anda mencapai integrasi yang sangat solid yang menghindari banyak kesalahan umum yang terjadi saat mencoba menghubungkan kedua platform secara manual dan tanpa lapisan bantuan ini.

Menghubungkan Laravel dengan Supabase untuk database dan penyimpanan, memanfaatkan driver Supabase khusus untuk mengelola UUID dengan lancar, dan menggunakan adaptor Flysystem untuk penyimpanan memungkinkan Anda membangun aplikasi modern di mana Seluruh infrastruktur kompleks dienkapsulasi Di balik layar API Laravel yang bersih, dari migrasi dan autentikasi hingga mengunggah file ke bucket yang aman.