Den ionCube Loader für die NextPDF-Premium-Editionen einrichten

Auf einen Blick

Einige NextPDF-Premium-Distributionen werden als ionCube-kodiertes PHP ausgeliefert, sodass der passende ionCube Loader in Ihrer PHP-Laufzeitumgebung installiert sein muss, bevor der Code läuft. Das betrifft:

Die Trial-Builds von NextPDF Pro und Enterprise sowie
den offiziellen (kostenpflichtigen) Build von NextPDF Pro.

Für die offizielle Auslieferung von NextPDF Enterprise hängt der Paketierungsmechanismus von Ihrer Vereinbarung ab. Folgen Sie den Auslieferungsanweisungen in Ihren Lizenzbedingungen, statt eine bestimmte Laufzeitumgebung anzunehmen; siehe Lizenzierung und Aktivierung.

Diese Seite ist eine praxisnahe Einrichtungsanleitung: was ionCube ist, wie Sie den Loader installieren und verifizieren, wo die Lizenzdatei für den kostenpflichtigen, ionCube-kodierten Pro-Build abgelegt wird, wie Sie ihn in Containern ausführen und wie Sie die häufigen Fehler beheben. Die unterstützte PHP-Version ist 8.4, und der Loader, den Sie installieren, muss exakt zu dieser Laufzeitumgebung passen.

Was ionCube ist und warum NextPDF es verwendet

ionCube ist ein kommerzieller PHP-Encoder, der mit einer kostenlosen Laufzeitkomponente namens ionCube Loader gekoppelt ist. Der Loader ist eine PHP-Erweiterung (Zend). Wenn PHP startet, erlaubt der Loader, dass die kodierten Dateien dekodiert und ausgeführt werden; ohne ihn kann eine kodierte Datei nicht laufen, und PHP meldet stattdessen einen Loader-Fehler.

NextPDF nutzt die ionCube-Kodierung, um den proprietären Premium-Quellcode zu schützen, und liefert dennoch installierbares PHP aus, das Sie wie jedes andere Composer-Paket bereitstellen und ausführen. Die Kodierung ändert nichts daran, wie Sie die Bibliothek aufrufen — Ihre Anwendung zielt auf dieselben öffentlichen Verträge —, sie ergänzt lediglich die Voraussetzung, dass der Loader in der Laufzeitumgebung vorhanden ist.

Für die Loader-Downloads und die maßgeblichen, versionsspezifischen Anweisungen nutzen Sie die Anbieterdokumentation unter ioncube.com (die Dokumentation und Installationsanleitung zum ionCube Loader). Diese Seite behandelt die NextPDF-spezifische Einrichtung; für den Loader selbst ist der Anbieter die maßgebliche Quelle.

Voraussetzungen

Installieren Sie den ionCube Loader, der in jeder Hinsicht zu Ihrer PHP-Laufzeitumgebung passt. Eine Abweichung bei nur einem dieser Punkte ist die häufigste Fehlerursache:

Achse	Muss übereinstimmen
PHP-Version	8.4 (NextPDF Premium erfordert `>=8.4 <9.0`).
Betriebssystem	Das Betriebssystem, auf das das Loader-Bundle abzielt (Linux, Windows, macOS).
Architektur	Die CPU-Architektur des Hosts, üblicherweise 64-Bit (`x86-64` oder `aarch64`).
Thread-Sicherheit	Non-Thread-Safe (NTS) oder Thread-Safe (ZTS), passend zu Ihrem PHP-Build.

Über den Loader hinaus benötigen Sie außerdem:

Das NextPDF-Premium-Paket, installiert über Composer — nextpdf/pro, nextpdf/enterprise oder das Metapaket nextpdf/premium.
Für kostenpflichtige Builds Ihre Lizenzdatei. Für den kostenpflichtigen, ionCube-kodierten Pro-Build siehe Lizenzplatzierung weiter unten.

Um Ihre aktuellen Build-Werte auszulesen, führen Sie php -i aus (oder rufen Sie phpinfo() auf) und prüfen Sie die Zeilen PHP Version, Architecture und Thread Safety. Bei den meisten CLI- und PHP-FPM-Bereitstellungen ist die Thread-Sicherheit deaktiviert (NTS); das klassische Apache-mod_php ist auf manchen Plattformen ZTS. Laden Sie das Loader-Bundle für genau diese Werte herunter.

Den Loader installieren

Die folgenden Schritte beschreiben den allgemeinen Ablauf. Für die genauen Dateinamen und das Verzeichnislayout des aktuellen Bundles ist die Dokumentation zum ionCube Loader auf ioncube.com maßgeblich.

Laden Sie das Loader-Bundle herunter, das zu Ihrer Umgebung passt (PHP 8.4, Ihr OS, Ihre Architektur und NTS/ZTS). Das Bundle enthält eine Loader-Datei pro PHP-Version und Thread-Sicherheitsvariante.
Legen Sie die Loader-Datei im PHP-Erweiterungsverzeichnis ab. Verwenden Sie das von php -i gemeldete extension_dir. Unter Linux/macOS heißt die Datei ioncube_loader_<os>_8.4.so (verwenden Sie ..._8.4_ts.so für einen ZTS-Build); unter Windows ist es ioncube_loader_win_8.4.dll (oder die ZTS-Variante ..._ts.dll).
Registrieren Sie ihn in php.ini als zend_extension. Der ionCube Loader muss als zend_extension geladen werden, nicht als gewöhnliche extension, und er sollte vor anderen Erweiterungen geladen werden. Fügen Sie eine einzelne Zeile mit einem absoluten Pfad zur Loader-Datei hinzu:
```
zend_extension=/full/path/to/ioncube_loader_lin_8.4.so
```
Unter Windows verwenden Sie den vollständigen Pfad zur .dll:
```
zend_extension="C:\php\ext\ioncube_loader_win_8.4.dll"
```
Wenn Ihre Plattform Include-Verzeichnisse im conf.d-Stil verwendet, platzieren Sie diese Zeile in einer Datei, die früh gelesen wird (zum Beispiel eine 00-ioncube.ini), damit sich der Loader vor anderen Erweiterungen initialisiert.
Starten Sie die PHP-Laufzeitumgebung neu. Starten Sie PHP-FPM, Ihren Webserver (Apache/Nginx) neu oder führen Sie schlicht die CLI erneut aus — je nachdem, was Ihre Anwendung ausführt. Ein langlaufender Prozess behält die alte Konfiguration, bis er neu gestartet wird.

Verifizieren

Bestätigen Sie, dass der Loader aktiv ist, bevor Sie versuchen, NextPDF zu laden.

Prüfen Sie zunächst das PHP-Versionsbanner. Wenn der Loader installiert ist, hängt php -v eine Zeile an, die ihn benennt:

php -v

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

Die Formulierung „with the ionCube PHP Loader“ ist das Signal, dass der Loader für diese Laufzeitumgebung aktiv ist. Bei einer Web-Bereitstellung (FPM / mod_php) reicht das CLI-Banner nicht aus — diese Laufzeitumgebung kann eine andere php.ini verwenden. Bestätigen Sie die Web-Laufzeitumgebung mit einem kleinen Skript, das vom Webserver ausgeliefert wird:

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

Bestätigen Sie schließlich, dass eine NextPDF-Premium-Klasse tatsächlich über den Autoloader von Composer geladen wird. Das beweist, dass der kodierte Code von Anfang bis Ende läuft:

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

Wenn php -v den Loader benennt, das Web-phpinfo() den ionCube-Abschnitt zeigt und die Premium-Klasse aufgelöst wird, ist der Loader korrekt eingerichtet.

Lizenzplatzierung (der kostenpflichtige, ionCube-kodierte Pro-Build)

ionCube verwendet ein einfaches Lizenzmodell: Der kodierte Code prüft zur Laufzeit auf eine Lizenzdatei und verweigert die Ausführung, wenn die Datei fehlt, nicht lesbar oder abgelaufen ist. Das gilt für den kostenpflichtigen, ionCube-kodierten Pro-Build — dafür legen Sie die mit Ihrem Kauf bereitgestellte Lizenzdatei dort ab, wo die Laufzeitumgebung sie finden kann.

Dieser ionCube-Lizenzdatei-Mechanismus ist spezifisch für den ionCube-kodierten Build. Für die offizielle Auslieferung von NextPDF Enterprise wird hier nicht angenommen, dass sie ionCube-kodiert ist; ihre Paketierung und Lizenzhandhabung richten sich nach Ihren Lizenzbedingungen — siehe Lizenzierung und Aktivierung.

Genaue Pfade sind umgebungsspezifisch, daher halten wir es allgemein:

Legen Sie die Lizenzdatei an dem Ort ab, den Ihre NextPDF-Auslieferungsanweisungen vorgeben — üblicherweise neben dem kodierten Paket oder in einem Verzeichnis, das die Anwendung lesen kann. Stellen Sie sicher, dass der Benutzer des PHP-Prozesses Leserechte hat.
Benennen Sie die Datei nicht um, sofern Ihre Anweisungen es nicht verlangen; der Loader sucht nach einem bestimmten Namen.
In Containern und bei schreibgeschützten Bereitstellungen mounten oder kopieren Sie die Lizenzdatei in das Image oder in einen beschreibbaren, lesbaren Pfad, den die Laufzeitumgebung sieht (siehe Docker und Container).

Die Lizenzdatei steuert die Aktivierung auf Laufzeitebene; sie ist getrennt von der Lizenz auf Anwendungsebene, die Ihre Edition und Ihre Funktionen auswählt. Für die Bedingungen, Laufzeiten und den Umfang Ihres Abonnements siehe Lizenzierung und Aktivierung und Ihren Lizenzvertrag — diese Seite legt keine Lizenzbedingungen fest.

Fehlerbehebung

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

Der Loader ist in der Laufzeitumgebung, die den Code ausgeführt hat, nicht aktiv, oder der Pfad ist falsch. Prüfen Sie erneut, dass die zend_extension-Zeile mit einem absoluten Pfad auf eine vorhandene Datei verweist, dass Sie die Laufzeitumgebung neu gestartet haben und dass Sie dieselbe Laufzeitumgebung (CLI vs. FPM) mit php -v / phpinfo() verifiziert haben. Eine Failed loading-Meldung bedeutet in der Regel, dass die Datei existiert, aber nicht zum PHP-Build passt (siehe nächster Punkt).

Abweichung bei PHP-Version, NTS/ZTS oder Architektur

Ein Loader, der für eine andere PHP-Version, einen anderen Thread-Sicherheitsmodus oder eine andere Architektur gebaut wurde, wird nicht geladen. Bestätigen Sie PHP Version, Thread Safety und Architecture aus php -i und installieren Sie dann die Loader-Datei für PHP 8.4 mit passendem NTS/ZTS und passender Bitbreite. Der Suffix 8.4 vs. 8.4_ts (oder _ts.dll) ist der Thread-Sicherheits-Selektor — den falschen zu verwenden, ist ein häufiger Fehler.

Loader-Ladereihenfolge

Der ionCube Loader muss ein zend_extension sein und sollte sich vor anderen Erweiterungen initialisieren. Wenn Sie Warnungen darüber sehen, dass der Loader nach anderen Erweiterungen geladen wird, verschieben Sie seine zend_extension-Zeile weiter nach vorn — oder geben Sie bei einem conf.d-Layout seiner Include-Datei einen Namen, der zuerst sortiert wird (zum Beispiel 00-ioncube.ini).

CLI, FPM und der Webserver verwenden unterschiedliche php.ini-Dateien

PHP lädt für die CLI häufig eine andere php.ini als für PHP-FPM oder mod_php. Wenn Sie nur die CLI konfigurieren, bleibt die Web-Laufzeitumgebung ohne Loader (oder umgekehrt). Führen Sie php --ini aus, um zu sehen, welche Datei die CLI verwendet, und prüfen Sie die Zeile Loaded Configuration File in der Web-phpinfo()-Ausgabe. Fügen Sie die zend_extension-Zeile in jede php.ini ein, die NextPDF ausführt, und starten Sie jede Laufzeitumgebung neu.

Lizenzdatei nicht gefunden oder abgelaufen

Beim kostenpflichtigen, ionCube-kodierten Pro-Build verhindert eine fehlende, nicht lesbare oder abgelaufene Lizenzdatei, dass der kodierte Code läuft. Verifizieren Sie, dass die Datei am erwarteten Ort liegt, dass der Benutzer des PHP-Prozesses sie lesen kann und dass sie nicht abgelaufen ist. Für Fragen zu Verlängerung und Laufzeit siehe Lizenzierung und Aktivierung und Ihren Lizenzvertrag.

OPcache-Wechselwirkungen

OPcache speichert kompilierte Skripte zwischen, aber ionCube-kodierte Dateien werden zur Laufzeit vom Loader dekodiert. Wenn Sie den Loader oder seine Konfiguration geändert haben und sich die Laufzeitumgebung weiterhin so verhält, als wäre er abwesend, starten Sie die PHP-Laufzeitumgebung neu (was OPcache leert), statt sich auf ein Hot-Reload zu verlassen. Halten Sie das ionCube-zend_extension registriert, sodass es vor OPcache lädt; die beiden koexistieren, und php -v sollte beide auflisten.

Docker und Container

Bei einer containerisierten Bereitstellung installieren Sie den Loader im Image und stellen sicher, dass er zum PHP-Build des Containers passt — nicht zu dem Ihres Hosts. Das Basis-Image legt die PHP-Version, das OS, die Architektur und den Thread-Sicherheitsmodus fest, laden Sie also das Loader-Bundle für diese Werte herunter.

Ein typischer Image-Build:

Starten Sie von einem PHP-8.4-Basis-Image (achten Sie darauf, ob es NTS oder ZTS ist — die offiziellen Tags php:8.4-cli / 8.4-fpm / 8.4-apache sind NTS, während Tags mit zts Thread-Safe sind; wählen Sie den Loader passend dazu).
Fügen Sie die passende ionCube-Loader-Datei dem extension_dir des Images hinzu.
Schreiben Sie die Zeile zend_extension=... in die php.ini des Images (oder ein conf.d-Include).
Stellen Sie für den kostenpflichtigen, ionCube-kodierten Pro-Build die Lizenzdatei bereit, indem Sie sie in das Image kopieren oder zur Laufzeit in einen Pfad mounten, den der Container lesen kann.

Da der Loader in das Image eingebaut ist, läuft derselbe Container überall identisch. Wenn Sie später das PHP des Basis-Images aktualisieren, ersetzen Sie die Loader-Datei durch den Build, der zur neuen Laufzeitumgebung passt.