Artikel

Mendeploy aplikasi web berbasis Laravel 12 ke layanan shared hosting seringkali memunculkan tantangan tersendiri. Salah satu kendala yang paling sering ditemui adalah munculnya pesan error berikut di terminal atau browser:

Composer detected issues in your platform: Your Composer dependencies require a PHP version ">= 8.2.0".

Error ini terjadi karena Laravel 12 mewajibkan penggunaan PHP minimal versi 8.2, sementara konfigurasi bawaan server shared hosting seringkali masih berada di versi yang lebih lama.

Berikut adalah panduan langkah demi langkah untuk menyelesaikan masalah tersebut dari awal hingga aplikasi berhasil berjalan (bebas Error 500).

Tahap 1: Menyamakan Versi PHP di Web Server dan Terminal (CLI)

Di shared hosting, pengaturan versi PHP untuk Web Server (yang menampilkan web di browser) dan Terminal/CLI (tempat menjalankan perintah Composer) seringkali terpisah. Keduanya harus disinkronkan.

1. Ubah Versi PHP Web Server: Masuk ke hPanel Hostinger > Tingkat Lanjut > Konfigurasi PHP. Pilih PHP 8.3 dan simpan.
2. Gunakan Binary PHP Spesifik di Terminal: Saat membuka Terminal/SSH dan masuk ke folder project, jangan hanya mengetik composer install. Gunakan path spesifik untuk PHP 8.3 agar terminal tidak memakai versi lama bawaan server:
3. Bash
   /opt/alt/php83/usr/bin/php /opt/cpanel/composer/bin/composer install

Tahap 2: Mengatasi Error Ekstensi PHP (dom dan xmlwriter)

Saat instalasi berjalan, Anda mungkin melihat teks merah bertuliskan it is missing from your system. Install or enable PHP's dom extension. Laravel membutuhkan beberapa modul dasar PHP untuk memproses struktur web.

• Solusi: Buka hPanel Hostinger > Konfigurasi PHP > tab Extensions. Cari dan centang ekstensi dom dan xmlwriter. Pastikan juga ekstensi standar lain seperti fileinfo, pdo_mysql, dan zip ikut tercentang.
• Optimasi Production: Jalankan ulang Composer dengan perintah khusus production agar proses instalasi lebih ringan:
  Bash
  /opt/alt/php83/usr/bin/php /opt/cpanel/composer/bin/composer install --optimize-autoloader --no-dev

Tahap 3: Melewati Batasan Keamanan Server (escapeshellarg)

Hosting seringkali mematikan (disable) beberapa fungsi PHP demi keamanan. Jika muncul error Call to undefined function Composer\Util\escapeshellarg(), ini berarti fungsi tersebut diblokir, padahal Laravel membutuhkannya untuk men-generate file autoload.

• Solusi Bypass: Anda bisa melewati eksekusi script otomatis ini dengan menambahkan parameter --no-scripts:
  Bash
  /opt/alt/php83/usr/bin/php /opt/cpanel/composer/bin/composer dump-autoload --optimize --no-scripts

Tahap 4: Mengatasi File .htaccess yang Hilang & Mengarahkan Document Root

Masalah: Meskipun PHP di terminal sudah versi 8.3, saat mengakses domain via browser, error PHP versi lama masih muncul. Ketika dicek di File Manager, file .htaccess ternyata tidak ada, dan panel hosting tidak memiliki fitur MultiPHP Manager untuk subdomain tersebut.

Solusi: Buat file .htaccess baru secara manual di root folder project Anda (sejajar dengan folder app, public, dll). File ini memiliki dua tugas krusial: mengarahkan pengunjung ke folder public (syarat wajib Laravel) dan memaksa server menggunakan PHP 8.3.

Peringatan Struktur Kode: Sangat sering terjadi kesalahan penulisan di mana aturan versi PHP diletakkan di dalam blok rewrite. Pastikan blok <IfModule mime_module> berada di luar penutup </IfModule> milik mod_rewrite agar server tidak kebingungan. Gunakan struktur kode berikut:

Apache

<IfModule mod_rewrite.c>
    RewriteEngine On

    # Mengarahkan semua request ke folder /public
    RewriteCond %{REQUEST_URI} !^/public/
    RewriteRule ^(.*)$ public/$1 [L]
</IfModule>

<IfModule mime_module>
    # Memaksa server menggunakan PHP 8.3 khusus untuk folder ini
    AddHandler application/x-httpd-alt-php83 .php .php8 .phtml
</IfModule>

Tahap 5: Menjinakkan Error 500 dan Membersihkan Cache Penuh

Setelah halaman berhasil diarahkan lewat .htaccess, biasanya akan muncul Error 500 atau pesan could not find driver. Ini adalah masalah koneksi database dan sisa cache konfigurasi lama.

1. Siapkan File .env: Pastikan file .env sudah ada. Sesuaikan kredensial database Anda. Jika password database mengandung karakter khusus (seperti =, %, atau ~), wajib dibungkus dengan tanda kutip ganda agar terbaca dengan benar:
   Cuplikan kode
   DB_PASSWORD="[DISENSOR_PASSWORD_ANDA]"
2. Aktifkan Driver MySQL: Kembali ke hPanel > Konfigurasi PHP > tab Extensions, dan pastikan pdo_mysql sudah tercentang aktif.
3. Generate Kunci Aplikasi & Bersihkan Cache: Karena script otomatis sempat di-bypass pada Tahap 3, dan untuk memastikan aplikasi membaca settingan database terbaru (bukan sisa konfigurasi lama), jalankan serangkaian perintah artisan ini di Terminal secara berurutan:
   Bash
   /opt/alt/php83/usr/bin/php artisan key:generate
/opt/alt/php83/usr/bin/php artisan config:clear
/opt/alt/php83/usr/bin/php artisan cache:clear
/opt/alt/php83/usr/bin/php artisan view:clear

Aktifkan semua fitur yang ada pada PHP
Setelah semua tahapan ini dilalui, aplikasi Laravel 12 Anda sudah siap digunakan secara live di server Hostinger!