Menyiapkan ionCube Loader untuk edisi premium NextPDF

Sekilas pandang

Beberapa distribusi premium NextPDF dikirimkan sebagai PHP berenkode ionCube, sehingga ionCube Loader yang sesuai harus terpasang pada runtime PHP Anda sebelum kode dapat berjalan. Ini berlaku untuk:

Build trial NextPDF Pro dan Enterprise, serta
Build resmi (berbayar) NextPDF Pro.

Untuk pengiriman resmi NextPDF Enterprise, mekanisme paketnya bergantung pada perjanjian Anda. Ikuti instruksi pengiriman dalam ketentuan lisensi Anda, bukan mengasumsikan runtime tertentu; lihat Pelisensian dan aktivasi.

Halaman ini adalah panduan penyiapan praktis: apa itu ionCube, cara memasang dan memverifikasi Loader, ke mana berkas lisensi ditempatkan untuk build Pro berenkode ionCube berbayar, cara menjalankannya dalam kontainer, dan cara memperbaiki kegagalan yang umum. Versi PHP yang didukung adalah 8.4, dan Loader yang Anda pasang harus cocok dengan runtime tersebut secara persis.

What ionCube is and why NextPDF uses it

ionCube adalah encoder PHP komersial yang dipasangkan dengan komponen runtime gratis bernama ionCube Loader. Loader ini adalah ekstensi PHP (Zend). Saat PHP dimulai, Loader memungkinkan berkas berenkode untuk didekode dan dieksekusi; tanpanya, berkas berenkode tidak dapat berjalan dan PHP justru melaporkan galat loader.

NextPDF menggunakan enkode ionCube untuk melindungi sumber premium berpemilik sekaligus tetap mengirimkan PHP yang dapat dipasang, yang Anda terapkan dan jalankan seperti paket Composer lainnya. Enkode ini tidak mengubah cara Anda memanggil pustaka — aplikasi Anda menargetkan kontrak publik yang sama — enkode hanya menambahkan persyaratan bahwa Loader harus hadir di runtime.

Untuk unduhan Loader dan instruksi otoritatif yang spesifik per versi, gunakan dokumentasi vendor di ioncube.com (dokumentasi dan panduan instalasi ionCube Loader). Halaman ini mencakup penyiapan yang khusus untuk NextPDF; vendor adalah sumber kebenaran untuk Loader itu sendiri.

Requirements

Pasang ionCube Loader yang cocok dengan runtime PHP Anda pada setiap aspek. Ketidakcocokan pada salah satu aspek ini adalah penyebab kegagalan yang paling umum:

Aspek	Harus cocok
Versi PHP	8.4 (NextPDF premium memerlukan `>=8.4 <9.0`).
Sistem operasi	OS yang menjadi target bundel Loader (Linux, Windows, macOS).
Arsitektur	Arsitektur CPU host, biasanya 64-bit (`x86-64` atau `aarch64`).
Keamanan thread	Non-thread-safe (NTS) atau thread-safe (ZTS), sesuai build PHP Anda.

Selain Loader, Anda juga memerlukan:

Paket premium NextPDF yang dipasang melalui Composer — nextpdf/pro, nextpdf/enterprise, atau metapackage nextpdf/premium.
Untuk build berbayar, berkas lisensi Anda. Untuk build Pro berenkode ionCube berbayar, lihat Penempatan lisensi di bawah.

Untuk membaca nilai build Anda saat ini, jalankan php -i (atau panggil phpinfo()) dan periksa baris PHP Version, Architecture, dan Thread Safety. Pada sebagian besar penerapan CLI dan PHP-FPM, keamanan thread dinonaktifkan (NTS); Apache mod_php klasik pada beberapa platform adalah ZTS. Unduh bundel Loader untuk nilai-nilai persis tersebut.

Install the Loader

Langkah-langkah di bawah ini adalah alur umum. Rujuk dokumentasi ionCube Loader di ioncube.com untuk nama berkas dan tata letak direktori yang persis dari bundel saat ini.

Unduh bundel Loader yang cocok dengan lingkungan Anda (PHP 8.4, OS, arsitektur, dan NTS/ZTS Anda). Bundel berisi satu berkas loader per versi PHP dan varian keamanan thread.
Tempatkan berkas loader di direktori ekstensi PHP. Gunakan extension_dir yang dilaporkan oleh php -i. Pada Linux/macOS berkasnya adalah ioncube_loader_<os>_8.4.so (gunakan ..._8.4_ts.so untuk build ZTS); pada Windows berkasnya adalah ioncube_loader_win_8.4.dll (atau varian ZTS ..._ts.dll).
Daftarkan di php.ini sebagai zend_extension. ionCube Loader harus dimuat sebagai zend_extension, bukan extension biasa, dan harus dimuat sebelum ekstensi lain. Tambahkan satu baris, menggunakan jalur absolut ke berkas loader:
```
zend_extension=/full/path/to/ioncube_loader_lin_8.4.so
```
Pada Windows, gunakan jalur lengkap ke .dll:
```
zend_extension="C:\php\ext\ioncube_loader_win_8.4.dll"
```
Jika platform Anda menggunakan direktori include bergaya conf.d, tempatkan baris ini di sebuah berkas yang dibaca lebih awal (misalnya 00-ioncube.ini) agar Loader diinisialisasi sebelum ekstensi lain.
Mulai ulang runtime PHP. Mulai ulang PHP-FPM, server web Anda (Apache/Nginx), atau cukup jalankan ulang CLI — mana pun yang menjalankan aplikasi Anda. Proses yang berjalan lama akan tetap memakai konfigurasi lama sampai dimulai ulang.

Verify

Pastikan Loader aktif sebelum Anda mencoba memuat NextPDF.

Pertama, periksa banner versi PHP. Ketika Loader terpasang, php -v menambahkan satu baris yang menamainya:

php -v

PHP 8.4.x (cli) ...
    with Zend OPcache v8.4.x, ...
    with the ionCube PHP Loader ...

Frasa “with the ionCube PHP Loader” adalah sinyal bahwa Loader aktif untuk runtime tersebut. Untuk penerapan web (FPM / mod_php), banner CLI saja tidak cukup — runtime tersebut dapat menggunakan php.ini yang berbeda. Pastikan runtime web dengan skrip kecil yang disajikan oleh server web:

<?php
// loader-check.php — delete after verifying.
var_dump(extension_loaded('ionCube Loader'));
phpinfo(); // The output includes an "ionCube PHP Loader" section when active.

Terakhir, pastikan bahwa sebuah kelas premium NextPDF benar-benar dimuat melalui autoloader Composer. Ini membuktikan kode berenkode berjalan dari ujung ke ujung:

<?php
require __DIR__ . '/vendor/autoload.php';

// A premium class resolves only when the Loader can decode the package.
var_dump(class_exists(\NextPDF\Pro\Document\PdfPortfolio::class));

Jika php -v menamai Loader, phpinfo() web menampilkan bagian ionCube, dan kelas premium ter-resolve, berarti Loader sudah disiapkan dengan benar.

Penempatan lisensi (build Pro berenkode ionCube berbayar)

ionCube menggunakan model pelisensian sederhana: kode berenkode memeriksa berkas lisensi saat runtime dan menolak berjalan ketika berkas hilang, tidak dapat dibaca, atau kedaluwarsa. Ini berlaku untuk build Pro berenkode ionCube berbayar — untuknya, Anda menempatkan berkas lisensi yang disediakan oleh pembelian Anda di tempat yang dapat ditemukan oleh runtime.

Mekanisme berkas lisensi ionCube ini khusus untuk build berenkode ionCube. Pengiriman resmi NextPDF Enterprise tidak diasumsikan berenkode ionCube di sini; paket dan penanganan lisensinya diatur oleh ketentuan lisensi Anda — lihat Pelisensian dan aktivasi.

Jalur yang persis bersifat spesifik per lingkungan, jadi jagalah agar tetap umum:

Tempatkan berkas lisensi di lokasi yang ditentukan oleh instruksi pengiriman NextPDF Anda — umumnya berdampingan dengan paket berenkode atau di direktori yang dapat dibaca aplikasi. Pastikan pengguna proses PHP memiliki izin baca.
Jangan mengganti nama berkas kecuali instruksi Anda menyatakannya; loader mencari nama tertentu.
Dalam kontainer dan pada penerapan read-only, kaitkan (mount) atau salin berkas lisensi ke dalam image atau ke jalur yang dapat ditulis dan dibaca yang terlihat oleh runtime (lihat Docker dan kontainer).

Berkas lisensi mengatur aktivasi di tingkat runtime; berkas ini terpisah dari lisensi tingkat aplikasi yang memilih edisi dan fitur Anda. Untuk ketentuan, durasi, dan apa yang menjadi hak langganan Anda, lihat Pelisensian dan aktivasi dan perjanjian lisensi Anda — halaman ini tidak mendefinisikan ketentuan lisensi.

Troubleshooting

”Loader not installed” / “Failed loading … ioncube_loader”

Loader tidak aktif di runtime yang menjalankan kode, atau jalurnya salah. Periksa ulang bahwa baris zend_extension menunjuk ke berkas yang ada dengan jalur absolut, bahwa Anda telah memulai ulang runtime, dan bahwa Anda memverifikasi runtime yang sama (CLI vs FPM) dengan php -v / phpinfo(). Pesan Failed loading biasanya berarti berkasnya ada tetapi tidak cocok dengan build PHP (lihat item berikutnya).

PHP version, NTS/ZTS, or architecture mismatch

Loader yang dibangun untuk versi PHP, mode keamanan thread, atau arsitektur yang berbeda tidak akan dimuat. Pastikan PHP Version, Thread Safety, dan Architecture dari php -i, lalu pasang berkas Loader untuk PHP 8.4 dengan NTS/ZTS dan bitness yang cocok. Sufiks 8.4 vs 8.4_ts (atau _ts.dll) adalah penyeleksi keamanan thread — memakai yang salah adalah kesalahan yang sering terjadi.

Loader load order

ionCube Loader harus berupa zend_extension dan harus diinisialisasi sebelum ekstensi lain. Jika Anda melihat peringatan tentang Loader yang dimuat setelah ekstensi lain, pindahkan baris zend_extension-nya lebih awal — atau, dengan tata letak conf.d, beri berkas include-nya nama yang diurutkan paling awal (misalnya 00-ioncube.ini).

CLI, FPM, and the web server use different php.ini files

PHP umumnya memuat php.ini yang berbeda untuk CLI dibanding untuk PHP-FPM atau mod_php. Mengonfigurasi CLI saja membuat runtime web tanpa Loader (atau sebaliknya). Jalankan php --ini untuk melihat berkas mana yang dipakai CLI, dan periksa baris Loaded Configuration File pada keluaran phpinfo() web. Tambahkan baris zend_extension ke setiap php.ini yang menjalankan NextPDF, dan mulai ulang setiap runtime.

License file not found or expired

Untuk build Pro berenkode ionCube berbayar, berkas lisensi yang hilang, tidak dapat dibaca, atau kedaluwarsa akan menghentikan kode berenkode dari berjalan. Pastikan berkas berada di lokasi yang diharapkan, bahwa pengguna proses PHP dapat membacanya, dan bahwa berkas belum kedaluwarsa. Untuk pertanyaan perpanjangan dan ketentuan, lihat Pelisensian dan aktivasi dan perjanjian lisensi Anda.

OPcache interactions

OPcache menyimpan skrip terkompilasi dalam cache, tetapi berkas berenkode ionCube didekode oleh Loader saat runtime. Jika Anda mengubah Loader atau konfigurasinya dan runtime masih berperilaku seolah Loader tidak ada, mulai ulang runtime PHP (yang membersihkan OPcache) daripada mengandalkan hot reload. Jaga agar zend_extension ionCube tetap terdaftar sehingga ia dimuat mendahului OPcache; keduanya berdampingan, dan php -v harus mencantumkan keduanya.

Docker dan kontainer

Dalam penerapan terkontainer, pasang Loader di dalam image, dan pastikan ia cocok dengan build PHP kontainer — bukan build host Anda. Base image menetapkan versi PHP, OS, arsitektur, dan mode keamanan thread, jadi unduh bundel Loader untuk nilai-nilai tersebut.

Build image yang umum:

Mulai dari base image PHP 8.4 (perhatikan apakah NTS atau ZTS — tag resmi php:8.4-cli / 8.4-fpm / 8.4-apache adalah NTS, sedangkan tag yang mengandung zts bersifat thread-safe; pilih Loader yang cocok).
Tambahkan berkas ionCube Loader yang cocok ke extension_dir image.
Tulis baris zend_extension=... ke dalam php.ini image (atau sebuah include conf.d).
Untuk build Pro berenkode ionCube berbayar, sediakan berkas lisensi dengan menyalinnya ke dalam image atau mengaitkannya (mount) saat runtime ke jalur yang dapat dibaca kontainer.

Karena Loader dibangun ke dalam image, kontainer yang sama berjalan identik di mana pun. Jika Anda kemudian meningkatkan versi PHP base image, ganti berkas Loader dengan build yang cocok dengan runtime baru.