Seharian Terjebak Error 500 di Laravel: Jurnal Menghubungkan macOS Localhost ke MySQL XAMPP Native

Pengerjaan Proyek Capstone D3 Informatika ketika transisi dari Front-End murni menuju database Back-End

Bagi mahasiswa D3 Informatika, mata kuliah Proyek Capstone Pengembangan Web adalah ujian sesungguhnya. Di fase ini, kita dituntut mengintegrasikan rancangan antarmuka visual (Front-End) yang telah rapi ke dalam logika server nyata (Back-End). Pekan ini, saya mengalaminya sendiri saat membangun aplikasi E-Lapor Warga menggunakan framework Laravel 11 dan XAMPP Native di perangkat macOs.

Semuanya tampak sempurna di layar, samapai saya mengetikkan perintah migrasi database dan disambut dengan layar merah bertuliskan internal server error. Artikel ini merangkum tiga masalah database fundamental yang berhasil saya pecahkan setelah "berdarah-darah" seharian penuh.

Masalah 1: Miskonstruksi Alamat Host dan SQLSTATE[HY000] [2002]

Ketika pertama kali mencoba menyalakan seeder data master awal menggunakan perintah php artisan db:seed, aplikasi melempar pengecualian query yang fata:

SQLSTATE[HY000] [2002] No such file or directory (Connection: mysql, Host: localhost)
# Atau terkadang muncul sebagai:
SQLSTATE[HY000] [2002] Connection refused

Akar Peyebab

Pada ekosistem macOS, kata kunci localhost memiliki perilaku khusus pada PHP PDO. PHP akan mengasumsikan koneksi harus dilewatkan melalui file UNIX socket fisik (yang jalurnya seringkali berbeda anatara bawaan OS dengan XAMPP Native). Ketika file socket tersebut tidak ditemukan di lokasi standar, koneksi langsung terputus.

Celakanya lagi, setelah diperikasa ke dalama file konfigurasi config/database.php, parameter host-nya terkunci secara manual (hardcode) seperti ini:

'connections' => [
'mysql' => [
'driver' => 'mysql',
'host' => 'localhost', // ❌ Mengabaikan isi dari file .env
'port' => '3306',
'database' => 'db_elapor_warga',
// ...
]
]

Pelajaran penting: Melakukan hardcode nilai konfigurasi di dalam folder config membuat fleksisbilitas .env menjadi tidak berguna.

Solusi yang Berhasil

Pertama, kembalikan kesaktian file .env dengan mengubah baris host pada config/database.php agar menggunakan helper env() bawaan Laravel:

'host' => env('DB_HOST', '127.0.0.1'),

Kedua, buka file .env di root proyek Anda, lalu paksa koneksi menggunakan protokol TCP/IP jaringan dengan mengubah localhost menjadi IP loopback 127.0.0.01 :

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=db_elapor_warga
DB_USERNAME=root
DB_PASSWORD=

Masalah 2: Tragedi Driver Sesi dan Misteri Missing Table ‘sessions’

Setelah masalah host teratasi, website sempat memunculkan halaman utama. Namun saat form dikirimkan atau halaman di-refresh, muncul error aneh baru yang mengarah pada komponen internal framework:

Illuminate\Database\QueryException - Internal Server Error
SQL: select * from `sessions` where `id` = ... limit 1
Previous exception: PDOException SQLSTATE[HY000] [2002]

Ketika saya mencoba memperbaiki dengan menjalankan perintah php artisan session:table dan diikuti php artisan migrate, terminal justru membalas dengan:

ERROR: Migration already exists.
INFO: Nothing to migrate.

Akar Penyebab

Pada file konfigurasi .env proyek E-Lapor Warga, manajemen sesi diatur menggunakan database:

SESSION_DRIVER=database

Artinya, setiap kali ada request halaman dari browser, Laravel wajib membaca dan menulis status autentikasi pengguna ke dalam tabel database bernama sessions. Namun, ketika dicek via phpMyAdmin, tabel tersebut tidak pernah terbentuk karena proses migrasi bawaan mengalami kegagalan struktural (corrupted migration history).

Solusi yang Berhasil

Untuk lingkungan pengembangan lokal ((local development environment), menyimpan sesi di dalam database sangatlah rawan memicu blocking-error jika koneksi database sedang tidak stabil. Solusi tercepat dan palinhg efisien adalah memindahkan penyimpanan sesi ke file sistem lokal komputer.

Get HelloSat’s stories in your inbox

Join Medium for free to get updates from this writer.

Remember me for faster sign in

Ubah pengaturan di file .env Anda:

# Ubah dari database menjadi file
SESSION_DRIVER=file

Dengan mengubah driver menjadi file, Laravel akan menyimpan token sesi pengguna ke dalam folder aman storage/framework/sessions/ . Website Anda akan langsung kembali normal tanpa perlu memusingkan ketiadaan tabel database sesi.

Masalah 3: Efek Rumah Kaca “Configuration Caching” di Laravel

Salah satu momen paling membuat frustrasi adalah ketika kode di file .env sudah diubah dengan benar, tetapi saat halaman browser di-refresh, error lama yang sama persis tetap muncul secara keras kepala.

Akar Penyebab

Laravel memiliki sistem optimasi yang sangat agresif bernama Configuration Caching. Saat sistem berjalan, Laravel memadatkan seluruh file konfigurasi ke dalam ssatu file memori cepat di folder bootstrap/cache/config.php . Selama file cache ini ada, perubahan fisik apa pun yang Anda lakukan pada file .env tidak akan pernah dibaca oleh sistem.

Solusi yang Berhasil

Setiap kali Anda melakukan perubahan sekecil apa pun pada file konfigurasi (.env atau file di dalam folder config/), jalankan baris perintah "Sapu Bersih Cache" di terminal VS Code Anda:

php artisan config:clear
php artisan cache:clear
php artisan view:clear

Perintah tersebut akan menghancurkan berkas-berkas samapah optimasi lawas dan memaksa mesin Laravel mendeteksi konfigurasi database baru yang segar.

Kesimpulan & Pelajaran untuk Pengembangan Pemula

Menghadapi error 500 (Internal Server Error) saat transisi Back-End adalah bagian dari ritme belajar yang sehat. Dari trouble seharian ini, ada 3 poin penting yang bisa kita bagikan ke sesama mahasiswa:

1. Gunakan Alamat IP Eksplisit: Jangan andalkan kata kunci localhost di macOS jika Anda menggunakan server lokal pihak ketiga seperti XAMPP atau MAMP. Gunakan selalu 127.0.0.1.
2. Sesi File Lebih Aman untuk Dev-Mode: Kecuali Anda benar-benar membutuhkan pencatatan sesi berskala besar, biarkan SESSION_DRIVER=file bekerja di laptop Anda agar meminimalisir dependensi tabel database bawaan.
3. Hormati Siklus Cache: Jangan buang waktu seharian mengedit kode tanpa pernah menjalankan perintah config:clear. Kemungkinan besar kesalahan Anda bukan pada logika kodenya, melainkan pada ingatan cache Laravel yang belum dibersihkan.

Sekarang, proyek E-Lapor Warga sudah kembali menyala dengan normal. Waktunya mengistirahatkan laptop, menyeduh kopi baru, dan bersiap membangun modul pengontrol kirim aduan berikutnya. Semangat ngoding!