Cara Memuat Ekstensi PHP Pihak Ketiga di ServBay

ServBay adalah lingkungan pengembangan web lokal yang powerful dan dilengkapi dengan beragam ekstensi PHP populer secara bawaan. Pengguna umumnya hanya perlu mengaktifkan dan mengonfigurasi ekstensi melalui menu Packages -> Languages -> PHP Version -> Extensions di ServBay.

Namun, kadangkala pengembang perlu memuat ekstensi PHP pihak ketiga atau hasil kompilasi sendiri yang tidak disertakan secara default oleh ServBay. Dokumen ini akan membimbing Anda secara detail tentang cara memuat ekstensi jenis ini ke versi PHP tertentu di ServBay, menggunakan ionCube Loader sebagai contoh. Langkah ini bisa diterapkan juga untuk ekstensi Zend lainnya atau file ekstensi .so hasil kompilasi Anda sendiri.

Catatan Penting tentang Zend Extension: ionCube Loader adalah Zend Extension—jenis ekstensi yang berinteraksi secara lebih mendalam dengan Zend Engine di PHP. Oleh karena itu, Anda harus menggunakan instruksi zend_extension dalam konfigurasi, bukan extension seperti umumnya untuk ekstensi standar. Pastikan Anda membedakan dan menggunakan instruksi yang tepat.

Prasyarat

• Anda telah menginstal dan menjalankan ServBay di sistem macOS.
• Anda memiliki hak akses administrator untuk mengakses file sistem dan antarmuka konfigurasi ServBay.
• Anda terbiasa menggunakan aplikasi Terminal di macOS.
• Anda sudah memiliki file ekstensi PHP pihak ketiga yang ingin dimuat (biasanya file .so), dan file tersebut SEPADAN sepenuhnya dengan versi PHP target di ServBay—termasuk arsitektur (Intel atau Apple Silicon) dan opsi kompilasi (NTS/ZTS).

Perhatian: Keserasian Arsitektur Sangat Penting

ServBay menyediakan paket PHP asli untuk arsitektur Intel (x86_64) dan Apple Silicon (ARM64, seperti chip M1/M2/M3/M4). Saat memuat file ekstensi .so, pastikan file tersebut telah dikompilasi untuk arsitektur yang SAMA persis dengan paket PHP yang digunakan ServBay.

File dengan arsitektur berbeda TIDAK bisa dicampur; ketidaksesuaian arsitektur akan menyebabkan PHP gagal dijalankan atau crash.

Anda dapat menggunakan perintah file untuk memeriksa arsitektur file executable atau file .so:

1. Cek arsitektur paket PHP milik ServBay (Silakan ganti 8.3 dengan versi PHP Anda):

   file /Applications/ServBay/package/php/8.3/current/bin/php

   Contoh output:

   /Applications/ServBay/package/php/8.3/current/bin/php: Mach-O 64-bit executable arm64 # Menandakan Apple Silicon ARM64

   atau

   /Applications/ServBay/package/php/8.3/current/bin/php: Mach-O 64-bit executable x86_64 # Menandakan Intel x86_64

2. Cek arsitektur ekstensi .so yang akan dimuat (ganti xdebug.so dengan nama file ekstensi Anda):

   file xdebug.so

   Contoh output:

   xdebug.so: Mach-O 64-bit bundle arm64 # Menandakan Apple Silicon ARM64

   atau

   xdebug.so: Mach-O 64-bit bundle x86_64 # Menandakan Intel x86_64

   Pastikan informasi arsitektur pada langkah 1 dan 2 benar-benar sama.

Langkah-langkah

Langkah 1: Unduh File Ekstensi Pihak Ketiga (Contoh: ionCube Loader)

1. Buka laman unduhan resmi ionCube Loader. Pilih versi sesuai arsitektur macOS Anda. Untuk macOS ARM64 (Mac seri Apple Silicon), unduh versi Darwin ARM64. Anda bisa langsung menggunakan tautan berikut (periksa apakah ada versi baru di situs resmi, tautan di bawah hanyalah contoh): https://downloads.ioncube.com/loader_downloads/ioncube_loaders_dar_arm64.tar.gz
2. Setelah diunduh, Anda akan mendapatkan file terkompresi .tar.gz, mis. ioncube_loaders_dar_arm64.tar.gz.

Langkah 2: Tentukan Versi PHP Target & Direktori Instalasi Ekstensi ServBay

1. Buka aplikasi ServBay.

2. Di panel navigasi kiri, klik Packages lalu Languages.

3. Di daftar kanan, cari versi PHP yang ingin Anda pasangi ionCube Loader (mis. PHP 8.3). Catat versi tersebut.

4. Temukan direktori instalasi ekstensi (extension_dir) milik PHP tersebut—tempat standar menyimpan file .so. Lokasi path tergantung pada lokasi instalasi, versi PHP, dan opsi kompilasi.

   Cara paling akurat adalah via perintah terminal:

   Buka Terminal dan jalankan (ganti path sesuai PHP Anda):

   /Applications/ServBay/package/php/8.3/current/bin/php -i | grep extension_dir

   Output akan menampilkan path, misal:

   extension_dir => /Applications/ServBay/package/php/8.3/8.3.16/lib/php/extensions/no-debug-non-zts-20230831

   Catat path ini untuk langkah berikutnya.

Langkah 3: Ekstrak dan Tempatkan File Loader

1. Buka Terminal.

2. Pindah ke folder tempat Anda mengunduh file .tar.gz (umumnya di ~/Downloads):

   cd ~/Downloads

3. Ekstrak file yang diunduh:

   tar -zxvf ioncube_loaders_dar_arm64.tar.gz

   Ini akan membuat folder baru bernama ioncube.

4. Masuk ke direktori ioncube:

   cd ioncube

5. Di dalam folder ini, terdapat file .so sesuai berbagai versi PHP, seperti ioncube_loader_dar_8.3.so. Temukan file yang cocok dengan versi PHP target Anda (misal 8.3).

6. Salin file .so tersebut ke direktori ekstensi PHP yang ditemukan di langkah 2. Misal tujuan instalasi:

   cp ioncube_loader_dar_8.3.so /Applications/ServBay/package/php/8.3/8.3.16/lib/php/extensions/no-debug-non-zts-20230831/

   • Pastikan untuk mengganti path /Applications/ServBay/.../no-debug-non-zts-20230831/ dengan path hasil perintah php -i pada langkah 2.
   • Pastikan file .so yang disalin BENAR-BENAR COCOK dengan versi PHP & arsitektur ServBay (lihat pengecekan arsitektur di Prasyarat).

Langkah 4: Konfigurasi PHP di ServBay

1. Kembali ke aplikasi ServBay.

2. Pastikan menu Languages terpilih, lalu klik versi PHP yang ingin Anda konfigurasi (misal PHP 8.3) di kanan.

3. Di area konfigurasi kanan, buka tab PHP.

4. Scroll ke bawah sampai menemukan kolom Additional Parameters.

5. Tambahkan instruksi berikut untuk memuat ionCube Loader (di baris baru bila sudah ada konfigurasi lain):

   zend_extension = ioncube_loader_dar_8.3.so

   • Penting: Ganti ioncube_loader_dar_8.3.so dengan nama file sebenarnya yang sudah Anda salin.
   • Gunakan zend_extension karena ionCube Loader adalah Zend Extension.
   • Karena file sudah ditempatkan di extension_dir, cukup tulis nama filenya saja—tidak perlu path lengkap.
   • Jika sudah ada konfigurasi lain, tambahkan di baris baru.

   (Tangkapan layar hanya sebagai contoh, tampilan nyata mungkin berbeda tergantung versi)

6. Klik Save (pojok kanan bawah) untuk menyimpan perubahan.

Langkah 5: Restart Layanan PHP

Setelah klik Save di ServBay, aplikasi otomatis akan mendeteksi perubahan konfigurasi dan melakukan restart layanan terkait (termasuk PHP) secara otomatis. Anda tidak perlu melakukan restart manual dalam kondisi normal.

Langkah 6: Verifikasi Ekstensi Berhasil Dimuat

Anda dapat melakukan verifikasi keberhasilan pemuatan ionCube Loader dengan dua metode populer berikut:

1. Verifikasi dari Command Line:

   • Buka Terminal.

   • Jalankan perintah berikut untuk melihat modul PHP yang dimuat (pakai path PHP yang sesuai):

     /Applications/ServBay/package/php/8.3/current/bin/php -m | grep -i ioncube

     Jika sukses, akan muncul baris seperti ionCube Loader.

   • Anda juga bisa menjalankan perintah ini untuk melihat detail versi:

     /Applications/ServBay/package/php/8.3/current/bin/php -v

     Contoh output ketika Loader telah dimuat (versi dapat berbeda):

     PHP 8.3.16 (cli) (built: Jan 31 2025 15:09:39) (NTS)
     Copyright (c) The PHP Group
     Zend Engine v4.3.16, Copyright (c) Zend Technologies
         with the ionCube PHP Loader v14.4.0, Copyright (c) 2002-2024, by ionCube Ltd.

     Perhatikan baris with the ionCube PHP Loader ....

2. Verifikasi melalui Fungsi phpinfo():

   • Buat file PHP baru di root situs Anda (mis. /Applications/ServBay/www/servbay.demo/ atau path situs Anda), misal info.php.
   • Isi file dengan konten berikut:

     <?php
     phpinfo();
     ?>

   • Akses file tersebut melalui browser, mis. http://servbay.demo/info.php (ganti dengan domain lokal Anda).
   • Cari "ionCube" di halaman (pakai Ctrl+F/Cmd+F). Jika Loader sudah termuat, akan ada blok info tentang ionCube Loader, termasuk versi, lisensi, dll.

Jika kedua cara di atas menampilkan informasi ionCube Loader, maka ekstensi sudah berhasil dimuat.

Masalah Umum & Solusi

• PHP gagal start/crash: Biasanya karena arsitektur ekstensi tidak cocok dengan arsitektur PHP yang dijalankan. Ulangi pengecekan seperti panduan Prasyarat. Versi PHP atau opsi kompilasi yang tidak cocok juga bisa menyebabkan masalah ini.
• Kesalahan path extension_dir: Pastikan file .so disalin ke path extension_dir yang sesuai untuk versi PHP terkait di ServBay. Selalu cek path dengan php -i | grep extension_dir.
• Kekeliruan instruksi konfigurasi: Cek perintah baru yang Anda tambahkan di kolom Additional Parameters apakah sudah benar. Zend Extensions wajib gunakan zend_extension = filename.so, sedangkan ekstensi biasa gunakan extension = filename.so. Nama file harus PERSIS sama, termasuk besar-kecil huruf.
• Masalah hak akses file: Pastikan user yang menjalankan ServBay (biasanya user macOS Anda) memiliki izin baca pada file dan direktori .so terkait. Umumnya tak masalah kecuali Anda mengubah permission secara manual.
• ServBay belum restart: Walau ServBay biasanya restart otomatis, jika perubahan belum efektif silakan coba restart layanan manual melalui antarmuka ServBay atau restart aplikasi.
• Tidak ada info di phpinfo(): Pastikan Anda membuka phpinfo() versi PHP yang dikelola ServBay dan sudah dikonfigurasi Loader-nya. Periksa juga jika terdapat beberapa versi PHP/situs, pastikan Anda cek yang tepat.

Ringkasan

Dengan mengikuti panduan langkah demi langkah di atas, Anda seharusnya dapat memuat ionCube Loader atau ekstensi PHP pihak ketiga lain berformat .so di PHP versi tertentu yang dikelola ServBay secara sukses. Kunci utama terletak pada identifikasi versi PHP target, penentuan direktori instalasi ekstensi (extension_dir), penempatan file ekstensi kompatibel, serta penambahan instruksi yang tepat (zend_extension atau extension) pada kolom Additional Parameters di antarmuka ServBay. Jika mengalami kendala, cek ulang bagian troubleshooting khususnya kecocokan arsitektur dan path file.