NextPDF Premium エディション向けの ionCube Loader をセットアップする

一目でわかる概要

一部の NextPDF Premium ディストリビューションは ionCube エンコードされた PHP として配布されるため、コードを実行する前に、対応する ionCube Loader を PHP ランタイムにインストールしておく必要があります。これは次のものに該当します。

• NextPDF Pro および Enterprise の 評価版 ビルド
• NextPDF Pro の 正式版（有料）ビルド

NextPDF Enterprise の 正式版 の納品では、パッケージングの仕組みはご契約内容によって異なります。特定のランタイムを前提とするのではなく、ライセンス条件に記載された納品手順に従ってください。ライセンスとアクティベーションを参照してください。

このページは実践的なセットアップガイドです。ionCube とは何か、Loader をインストールして検証する方法、有料の ionCube エンコード版 Pro ビルドでライセンスファイルを配置する場所、コンテナでの実行方法、そして一般的な失敗の対処方法を扱います。サポート対象の PHP バージョンは 8.4 であり、インストールする Loader はそのランタイムに正確に一致している必要があります。

ionCube とは何か、なぜ NextPDF が使用するのか

ionCube は商用の PHP エンコーダーで、ionCube Loader という無償のランタイムコンポーネントと組み合わせて使用します。Loader は PHP（Zend）拡張機能です。PHP が起動すると、Loader によってエンコードされたファイルがデコードされ、実行できるようになります。Loader がなければ、エンコードされたファイルは実行できず、PHP は代わりに Loader エラーを報告します。

NextPDF は ionCube エンコードを使用して、独自の Premium ソースを保護しつつ、他の Composer パッケージと同じようにデプロイして実行できるインストール可能な PHP として配布します。エンコードによってライブラリの呼び出し方が変わることはありません。アプリケーションは同じパブリックコントラクトを対象とし続け、Loader がランタイムに存在するという要件が追加されるだけです。

Loader のダウンロードと、バージョン固有の信頼できる手順については、ioncube.com のベンダードキュメント（ionCube Loader のドキュメントおよびインストールガイド）を参照してください。このページでは NextPDF 固有のセットアップを扱います。Loader 自体については、ベンダーが信頼できる情報源です。

要件

PHP ランタイムにあらゆる軸で一致する ionCube Loader をインストールしてください。いずれか 1 つでも不一致があると、失敗の最も一般的な原因になります。

軸	一致させる必要があるもの
PHP バージョン	8.4（NextPDF Premium は >=8.4 <9.0 を必要とする）。
オペレーティングシステム	Loader バンドルが対象とする OS（Linux、Windows、macOS）。
アーキテクチャ	ホストの CPU アーキテクチャ。通常は 64 ビット（x86-64 または aarch64）。
スレッドセーフ	PHP ビルドに一致する、非スレッドセーフ（NTS）またはスレッドセーフ（ZTS）。

Loader のほかに、次のものも必要です。

• Composer 経由でインストールされた NextPDF Premium パッケージ — nextpdf/pro、 nextpdf/enterprise、または nextpdf/premium メタパッケージ。
• 有料ビルドの場合は、ライセンスファイル。有料の ionCube エンコード版 Pro ビルドについては、後述のライセンスの配置 を参照してください。

現在のビルド値を確認するには、php -i を実行する（または phpinfo() を呼び出す）か、PHP Version、Architecture、Thread Safety の各行を確認します。ほとんどの CLI および PHP-FPM のデプロイメントではスレッドセーフは 無効（NTS）です。一部のプラットフォームの従来型 Apache mod_php は ZTS です。それらの正確な値に対応する Loader バンドルをダウンロードしてください。

Loader をインストールする

以下の手順は一般的な流れです。現在のバンドルの正確なファイル名やディレクトリ構成については、ioncube.com の ionCube Loader ドキュメントに従ってください。

1. ご利用の環境（PHP 8.4、OS、アーキテクチャ、NTS/ZTS）に一致する Loader バンドルをダウンロード します。バンドルには、PHP バージョンとスレッドセーフのバリアントごとに 1 つの 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（または ZTS バリアントの ..._ts.dll）です。

3. php.ini に zend_extension として登録します。 ionCube Loader は、通常の extension ではなく zend_extension として読み込む必要があり、他の拡張機能より 前 に読み込むようにします。Loader ファイルへの絶対パスを使って、1 行を追加します。

   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 形式のインクルードディレクトリを使用している場合は、Loader が他の拡張機能より先に初期化されるよう、この行を 早い段階 で読み込まれるファイル（たとえば 00-ioncube.ini）に配置してください。

4. PHP ランタイムを再起動します。 PHP-FPM、ご利用の Web サーバー（Apache/Nginx）を再起動するか、アプリケーションを実行する CLI を単純に再実行します。実行している方を再起動してください。長時間実行されるプロセスは、再起動するまで古い構成を保持します。

検証する

NextPDF を読み込もうとする前に、Loader が有効であることを確認してください。

まず、PHP バージョンのバナーを確認します。Loader がインストールされていると、php -v はそれを示す行を追加します。

php -v

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

“with the ionCube PHP Loader” という語句は、そのランタイムで Loader が有効であることを示す信号です。Web（FPM / mod_php）デプロイメントの場合、CLI バナーだけでは不十分です。そのランタイムは別の php.ini を使用している可能性があります。Web サーバーが配信する小さなスクリプトで、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.

最後に、NextPDF Premium のクラスが 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 を示し、Web の phpinfo() に ionCube セクションが表示され、Premium クラスが解決されれば、Loader は正しくセットアップされています。

ライセンスの配置（有料の ionCube エンコード版 Pro ビルド）

ionCube はシンプルなライセンスモデルを使用します。エンコードされたコードは、実行時に ライセンスファイル をチェックし、そのファイルが見つからない、読み取れない、または期限切れの場合は実行を拒否します。これは 有料の ionCube エンコード版 Pro ビルド に該当します。このビルドでは、購入時に提供されるライセンスファイルを、ランタイムが見つけられる場所に配置します。

この ionCube のライセンスファイルの仕組みは、ionCube エンコード版ビルド固有のものです。ここでは NextPDF Enterprise の 正式版 の納品が ionCube エンコードされているとは想定していません。そのパッケージングとライセンスの取り扱いは、ライセンス条件によって定められます。ライセンスとアクティベーションを参照してください。

正確なパスは環境によって異なるため、ここでは一般的な内容にとどめます。

• NextPDF の納品手順で指定された場所にライセンスファイルを配置してください。一般的には、エンコードされたパッケージと同じ場所か、アプリケーションが読み取れるディレクトリです。PHP プロセスのユーザーに読み取り権限があることを確認してください。
• 手順で指示がない限り、ファイル名を変更しないでください。Loader は特定の名前を探します。
• コンテナや読み取り専用のデプロイメントでは、ライセンスファイルをイメージにマウントまたはコピーするか、ランタイムから見える書き込み可能で読み取り可能なパスに配置してください（Docker とコンテナを参照）。

ライセンスファイルは、ランタイムレベルでのアクティベーションを制御します。これは、エディションと機能を選択するアプリケーションレベルのライセンスとは別物です。条件、期間、サブスクリプションに含まれる権限については、ライセンスとアクティベーションとライセンス契約を参照してください。このページでライセンス条件を定義することはありません。

トラブルシューティング

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

コードを実行したランタイムで Loader が有効になっていないか、パスが間違っています。zend_extension の行が絶対パスで既存のファイルを指していること、ランタイムを再起動したこと、そして 同じ ランタイム（CLI と FPM）を php -v / phpinfo() で検証したことを再確認してください。Failed loading というメッセージは通常、ファイルは存在するものの PHP ビルドに一致していないことを意味します（次の項目を参照）。

PHP version, NTS/ZTS, or architecture mismatch

異なる PHP バージョン、スレッドセーフモード、またはアーキテクチャ向けにビルドされた Loader は読み込まれません。php -i から PHP Version、Thread Safety、Architecture を確認し、一致する NTS/ZTS とビット数を備えた PHP 8.4 用の Loader ファイルをインストールしてください。8.4 と 8.4_ts（または _ts.dll）のサフィックスはスレッドセーフのセレクターであり、誤ったものを使うのはよくある間違いです。

Loader load order

ionCube Loader は zend_extension でなければならず、他の拡張機能より前に初期化されるようにします。Loader が他の拡張機能の後に読み込まれるという警告が表示される場合は、zend_extension の行をより前に移動してください。あるいは conf.d レイアウトでは、インクルードファイルに最初にソートされる名前（たとえば 00-ioncube.ini）を付けてください。

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

PHP は一般に、CLI 用と PHP-FPM または mod_php 用で異なる php.ini を読み込みます。CLI のみを構成すると、Web ランタイムには Loader がない状態（またはその逆）になります。CLI が使用するファイルを確認するには php --ini を実行し、Web の phpinfo() 出力で Loaded Configuration File の行を確認してください。NextPDF を実行する すべての php.ini に zend_extension の行を追加し、各ランタイムを再起動してください。

License file not found or expired

有料の ionCube エンコード版 Pro ビルドでは、ライセンスファイルが見つからない、読み取れない、または期限切れの場合、エンコードされたコードの実行が停止します。ファイルが想定された場所にあること、PHP プロセスのユーザーが読み取れること、そして期限が切れていないことを確認してください。更新や期間に関する質問については、ライセンスとアクティベーションとライセンス契約を参照してください。

OPcache interactions

OPcache はコンパイル済みスクリプトをキャッシュしますが、ionCube エンコードされたファイルは実行時に Loader によってデコードされます。Loader またはその構成を変更したのにランタイムが依然として Loader がないかのように動作する場合は、ホットリロードに頼るのではなく、PHP ランタイムを再起動してください（これにより OPcache がクリアされます）。ionCube の zend_extension を登録したままにして OPcache より前に読み込まれるようにしてください。両者は共存でき、php -v には両方が表示されるはずです。

Docker とコンテナ

コンテナ化されたデプロイメントでは、イメージ内に Loader をインストールし、ホストではなく コンテナの PHP ビルドに一致していることを確認してください。ベースイメージが PHP バージョン、OS、アーキテクチャ、スレッドセーフモードを固定するため、それらの値に対応する 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 インクルード）に書き込みます。
4. 有料の ionCube エンコード版 Pro ビルドでは、ライセンスファイルをイメージにコピーするか、コンテナが読み取れるパスに実行時にマウントして提供します。

Loader はイメージに組み込まれているため、同じコンテナはどこでも同じように動作します。後でベースイメージの PHP をアップグレードする場合は、Loader ファイルを新しいランタイムに一致するビルドに置き換えてください。

関連項目

• ライセンスとアクティベーション
• NextPDF Premium
• 進め方を選ぶ