跳到內容
NextPDF

為 NextPDF 商業版設定 ionCube Loader

概覽

標題為「概覽」的區段

部分 NextPDF 商業版發行版會以 ionCube 編碼 的 PHP 形式交付，因此在程式碼能運行之前，必須先於你的 PHP 執行階段安裝對應的 ionCube Loader。這適用於：

  • NextPDF Pro 與 Enterprise 的 試用 建置，以及
  • NextPDF Pro 的 正式（付費）建置。

至於 NextPDF Enterprise 正式版 的交付，其封裝機制取決於你的合約內容。請依循授權條款中的交付指示，而非假設採用特定的執行階段；參見 授權與啟用。

本頁是一份實務設定指南：什麼是 ionCube、如何安裝與驗證 Loader、付費且以 ionCube 編碼的 Pro 建置其授權檔案要放在哪裡、如何在容器中運行，以及如何修復常見的失敗情況。支援的 PHP 版本是 8.4，而你安裝的 Loader 必須與該執行階段完全相符。

什麼是 ionCube，以及 NextPDF 為何採用它

標題為「什麼是 ionCube，以及 NextPDF 為何採用它」的區段

ionCube 是一套商業 PHP 編碼器，並搭配一個名為 ionCube Loader 的免費執行階段元件。Loader 是一個 PHP（Zend）擴充功能。當 PHP 啟動時，Loader 會讓編碼過的檔案得以解碼並執行；少了它，編碼過的檔案就無法運行，PHP 會改為回報 loader 錯誤。

NextPDF 採用 ionCube 編碼來保護專有的商業版原始碼，同時仍交付可安裝的 PHP，讓你能像任何其他 Composer 套件一樣部署並運行。編碼並不會改變你呼叫函式庫的方式——你的應用程式仍以同一組公用合約為目標——它只是額外要求執行階段中必須存在 Loader。

關於 Loader 的下載，以及具權威性、針對特定版本的指示，請使用 ioncube.com 的廠商文件（即 ionCube Loader 文件與安裝指南）。本頁涵蓋 NextPDF 專屬的設定；Loader 本身則以廠商為準。

需求

標題為「需求」的區段

請安裝在每個面向都與你的 PHP 執行階段相符的 ionCube Loader。其中任一面向不符，都是最常見的失敗原因：

AxisMust match
PHP version8.4（NextPDF 商業版要求 >=8.4 <9.0）。
Operating systemLoader 套組所針對的作業系統（Linux、Windows、macOS）。
Architecture主機的 CPU 架構，通常為 64 位元（x86-64 或 aarch64）。
Thread safety非執行緒安全（NTS）或執行緒安全（ZTS），與你的 PHP 建置相符。

除了 Loader 之外，你還需要：

  • 透過 Composer 安裝的 NextPDF 商業版套件——nextpdf/pro、nextpdf/enterprise，或 nextpdf/premium 整合套件（metapackage）。
  • 對付費建置而言，需要你的 授權檔案。對付費且以 ionCube 編碼的 Pro 建置，請參見下方的 授權檔案放置位置。

若要讀取你目前的建置值，請執行 php -i（或呼叫 phpinfo()），並檢查 PHP Version、Architecture 與 Thread Safety 各行。在多數 CLI 與 PHP-FPM 部署中，執行緒安全是 停用 的（NTS）；某些平台上的傳統 Apache mod_php 則是 ZTS。請下載與這些確切值相符的 Loader 套組。

安裝 Loader

標題為「安裝 Loader」的區段

下列步驟是一般性流程。檔案的確切名稱與目前套組的目錄配置，請以 ioncube.com 上的 ionCube Loader 文件為準。

  1. 下載與你環境相符的 Loader 套組（PHP 8.4、你的作業系統、架構，以及 NTS/ZTS）。該套組為每個 PHP 版本與執行緒安全變體各包含一個 loader 檔案。

  2. 將 loader 檔案放入 PHP 擴充功能目錄。 請使用 php -i 回報的 extension_dir。在 Linux/macOS 上，檔案為 ioncube_loader_<os>_8.4.so（ZTS 建置請用 ..._8.4_ts.so）；在 Windows 上則是 ioncube_loader_win_8.4.dll（或 ..._ts.dll 這個 ZTS 變體）。

  3. 在 php.ini 中以 zend_extension 註冊它。 ionCube Loader 必須以 zend_extension 載入，而非一般的 extension，且應在其他擴充功能 之前 載入。請以指向 loader 檔案的絕對路徑，新增一行：

    zend_extension=/full/path/to/ioncube_loader_lin_8.4.so

    在 Windows 上，請使用 .dll 的完整路徑：

    zend_extension="C:\php\ext\ioncube_loader_win_8.4.dll"

    若你的平台採用 conf.d 形式的 include 目錄，請將這一行放在會被 較早 讀取的檔案中（例如 00-ioncube.ini），讓 Loader 在其他擴充功能之前初始化。

  4. 重新啟動 PHP 執行階段。 重新啟動 PHP-FPM、你的網頁伺服器（Apache/Nginx），或單純重新執行 CLI——以實際運行你應用程式的那一個為準。長時間運行的程序在重新啟動之前，會持續沿用舊的組態。

驗證

標題為「驗證」的區段

在嘗試載入 NextPDF 之前，請先確認 Loader 已啟用。

首先，檢查 PHP 版本橫幅。當 Loader 已安裝時，php -v 會附加一行標示它的訊息：

Terminal window
php -v
PHP 8.4.x (cli) ...
    with Zend OPcache v8.4.x, ...
    with the ionCube PHP Loader ...

「with the ionCube PHP Loader」 這串文字，就是該執行階段已啟用 Loader 的訊號。對於網頁（FPM / mod_php）部署而言，光看 CLI 橫幅並不足夠——那個執行階段可能使用不同的 php.ini。請透過網頁伺服器提供的一段小腳本，確認網頁執行階段：

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

最後，確認某個 NextPDF 商業版類別確實能透過 Composer 的自動載入器載入。這可證明編碼過的程式碼能從頭到尾運行：

<?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));

若 php -v 標示出 Loader、網頁的 phpinfo() 顯示 ionCube 區段，且商業版類別能解析成功，就表示 Loader 已正確設定完成。

授權檔案放置位置（付費的 ionCube 編碼 Pro 建置）

標題為「授權檔案放置位置（付費的 ionCube 編碼 Pro 建置）」的區段

ionCube 採用簡單的授權模式：編碼過的程式碼會在執行階段檢查是否有 授權檔案，當該檔案缺失、無法讀取或已過期時就拒絕運行。這適用於 付費且以 ionCube 編碼的 Pro 建置——對它而言，你要把你購買所提供的授權檔案，放在執行階段找得到的位置。

這套 ionCube 授權檔案機制是專屬於 ionCube 編碼建置的。此處並不假設 NextPDF Enterprise 正式版 的交付是以 ionCube 編碼；其封裝與授權處理由你的授權條款規範——參見 授權與啟用。

確切路徑因環境而異，因此這裡僅作概略說明：

  • 將授權檔案放在你的 NextPDF 交付指示所指定的位置——通常與編碼過的套件並列，或放在應用程式可讀取的目錄中。請確保 PHP 程序使用者具有讀取權限。
  • 除非你的指示要求，否則不要更名該檔案；loader 會尋找一個特定的名稱。
  • 在容器與唯讀部署中，請將授權檔案掛載或複製進映像檔，或放到執行階段看得見、且可寫入又可讀取的路徑（參見 Docker 與容器）。

授權檔案管理的是執行階段層級的啟用；它與用來選定你的版本與功能的應用程式層級授權是分開的。關於條款、期間，以及你的訂閱所授予的內容，請參見 授權與啟用 與你的授權合約——本頁並不定義授權條款。

疑難排解

標題為「疑難排解」的區段

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

標題為「”Loader not installed” / “Failed loading … ioncube_loader”」的區段

Loader 在實際執行該程式碼的執行階段中並未啟用，或路徑有誤。請重新檢查 zend_extension 那一行是否以絕對路徑指向一個確實存在的檔案、你是否重新啟動了執行階段，以及你是否以 php -v / phpinfo() 驗證了 同一個 執行階段（CLI vs FPM）。Failed loading 訊息通常表示檔案存在，但與該 PHP 建置不符（參見下一項）。

PHP 版本、NTS/ZTS 或架構不符

標題為「PHP 版本、NTS/ZTS 或架構不符」的區段

為不同 PHP 版本、執行緒安全模式或架構所建置的 Loader，將無法載入。請從 php -i 確認 PHP Version、Thread Safety 與 Architecture，然後安裝對應 PHP 8.4、且 NTS/ZTS 與位元數相符的 Loader 檔案。8.4 與 8.4_ts（或 _ts.dll）這個後綴正是執行緒安全的選擇器——用錯是常見的失誤。

Loader 載入順序

標題為「Loader 載入順序」的區段

ionCube Loader 必須是 zend_extension，且應在其他擴充功能之前初始化。若你看到關於 Loader 在其他擴充功能之後才載入的警告，請將其 zend_extension 那一行往前移——或者，若採用 conf.d 配置，請為其 include 檔案取一個會排在最前面的名稱（例如 00-ioncube.ini）。

CLI、FPM 與網頁伺服器使用不同的 php.ini 檔案

標題為「CLI、FPM 與網頁伺服器使用不同的 php.ini 檔案」的區段

PHP 為 CLI 載入的 php.ini，常與為 PHP-FPM 或 mod_php 載入的不同。只設定 CLI，會讓網頁執行階段沒有 Loader（反之亦然）。請執行 php --ini 查看 CLI 使用哪個檔案，並在網頁的 phpinfo() 輸出中檢查 Loaded Configuration File 那一行。請將 zend_extension 那一行加入 每一個 會運行 NextPDF 的 php.ini，並重新啟動每個執行階段。

找不到授權檔案或授權檔案已過期

標題為「找不到授權檔案或授權檔案已過期」的區段

對付費且以 ionCube 編碼的 Pro 建置而言，授權檔案缺失、無法讀取或已過期，都會讓編碼過的程式碼停止運行。請確認該檔案位於預期的位置、PHP 程序使用者可讀取它，且它尚未過期。關於續約與期間的問題，請參見 授權與啟用 與你的授權合約。

OPcache 互動

標題為「OPcache 互動」的區段

OPcache 會快取已編譯的腳本，但以 ionCube 編碼的檔案是由 Loader 在執行階段解碼的。若你更動了 Loader 或其組態，而執行階段仍表現得彷彿 Loader 不存在，請重新啟動 PHP 執行階段（這會清除 OPcache），而不要仰賴熱重載。請讓 ionCube 的 zend_extension 保持註冊，使它在 OPcache 之前載入；兩者可共存，且 php -v 應同時列出這兩者。

Docker 與容器

標題為「Docker 與容器」的區段

在容器化部署中，請把 Loader 安裝 在映像檔內，並確保它與 容器的 PHP 建置相符——而非你主機的。基底映像檔已固定了 PHP 版本、作業系統、架構與執行緒安全模式，因此請下載對應這些值的 Loader 套組。

一個典型的映像檔建置：

  1. 從 PHP 8.4 基底映像檔開始（注意它是 NTS 還是 ZTS——官方的 php:8.4-cli / 8.4-fpm / 8.4-apache 標籤為 NTS，而含有 zts 的標籤則為執行緒安全；請挑選相符的 Loader）。
  2. 將相符的 ionCube Loader 檔案加入映像檔的 extension_dir。
  3. 將 zend_extension=... 那一行寫入映像檔的 php.ini（或某個 conf.d include）。
  4. 對付費且以 ionCube 編碼的 Pro 建置，請藉由將授權檔案複製進映像檔，或在執行階段掛載到容器可讀取的路徑，來提供該檔案。

由於 Loader 已內建於映像檔中，同一個容器在任何地方都能以完全一致的方式運行。若你日後升級了基底映像檔的 PHP，請將 Loader 檔案替換為與新執行階段相符的建置。

另請參閱

標題為「另請參閱」的區段