Configurer le Loader ionCube pour les éditions premium de NextPDF

En bref

Certaines distributions premium de NextPDF sont livrées sous forme de PHP encodé avec ionCube : le Loader ionCube correspondant doit donc être installé dans ton runtime PHP avant que le code puisse s’exécuter. Cela s’applique à :

Les versions d’évaluation NextPDF Pro et Enterprise, et
La version officielle (payante) de NextPDF Pro.

Pour la livraison officielle de NextPDF Enterprise, le mécanisme d’empaquetage dépend de ton contrat. Suis les instructions de livraison indiquées dans tes conditions de licence plutôt que de présumer un runtime particulier ; voir Licence et activation.

Cette page est un guide de configuration pratique : ce qu’est ionCube, comment installer et vérifier le Loader, où placer le fichier de licence pour la version Pro payante encodée avec ionCube, comment l’exécuter dans des conteneurs et comment corriger les défaillances courantes. La version de PHP prise en charge est 8.4, et le Loader que tu installes doit correspondre exactement à ce runtime.

What ionCube is and why NextPDF uses it

ionCube est un encodeur PHP commercial associé à un composant de runtime gratuit appelé le Loader ionCube. Le Loader est une extension PHP (Zend). Au démarrage de PHP, le Loader permet de décoder et d’exécuter les fichiers encodés ; sans lui, un fichier encodé ne peut pas s’exécuter et PHP signale une erreur de loader à la place.

NextPDF utilise l’encodage ionCube pour protéger la source premium propriétaire tout en livrant du PHP installable que tu déploies et exécutes comme n’importe quel autre paquet Composer. L’encodage ne change pas la façon dont tu appelles la bibliothèque — ton application cible les mêmes contrats publics — il ajoute seulement l’exigence que le Loader soit présent dans le runtime.

Pour les téléchargements du Loader et les instructions faisant autorité, spécifiques à chaque version, utilise la documentation de l’éditeur sur ioncube.com (la documentation du Loader ionCube et le guide d’installation). Cette page couvre la configuration spécifique à NextPDF ; l’éditeur est la source de vérité pour le Loader lui-même.

Requirements

Installe le Loader ionCube qui correspond à ton runtime PHP sur chaque axe. Une non-correspondance sur l’un d’entre eux est la cause de défaillance la plus fréquente :

Axe	Doit correspondre à
Version de PHP	8.4 (NextPDF premium exige `>=8.4 <9.0`).
Système d’exploitation	Le système d’exploitation ciblé par le bundle du Loader (Linux, Windows, macOS).
Architecture	L’architecture CPU de l’hôte, généralement 64 bits (`x86-64` ou `aarch64`).
Sûreté des threads	Non thread-safe (NTS) ou thread-safe (ZTS), selon ta version de PHP.

Au-delà du Loader, tu as également besoin de :

Le paquet premium NextPDF installé via Composer — nextpdf/pro, nextpdf/enterprise, ou le métapaquet nextpdf/premium.
Pour les versions payantes, ton fichier de licence. Pour la version Pro payante encodée avec ionCube, voir Placement de la licence ci-dessous.

Pour lire les valeurs de ta version actuelle, exécute php -i (ou appelle phpinfo()) et examine les lignes PHP Version, Architecture et Thread Safety. Sur la plupart des déploiements CLI et PHP-FPM, la sûreté des threads est désactivée (NTS) ; le classique mod_php d’Apache est en ZTS sur certaines plateformes. Télécharge le bundle du Loader correspondant à ces valeurs exactes.

Install the Loader

Les étapes ci-dessous décrivent le déroulement général. Réfère-toi à la documentation du Loader ionCube sur ioncube.com pour connaître les noms de fichiers exacts et l’organisation des répertoires du bundle actuel.

Télécharge le bundle du Loader qui correspond à ton environnement (PHP 8.4, ton système d’exploitation, ton architecture et NTS/ZTS). Le bundle contient un fichier de loader par version de PHP et par variante de sûreté des threads.
Place le fichier du loader dans le répertoire d’extensions de PHP. Utilise le extension_dir indiqué par php -i. Sur Linux/macOS, le fichier est ioncube_loader_<os>_8.4.so (utilise ..._8.4_ts.so pour une version ZTS) ; sur Windows, c’est ioncube_loader_win_8.4.dll (ou la variante ZTS ..._ts.dll).
Enregistre-le dans php.ini en tant que zend_extension. Le Loader ionCube doit se charger en tant que zend_extension, pas en tant que simple extension, et il doit se charger avant les autres extensions. Ajoute une seule ligne, en utilisant un chemin absolu vers le fichier du loader :
```
zend_extension=/full/path/to/ioncube_loader_lin_8.4.so
```
Sous Windows, utilise le chemin complet vers le .dll :
```
zend_extension="C:\php\ext\ioncube_loader_win_8.4.dll"
```
Si ta plateforme utilise des répertoires d’inclusion de type conf.d, place cette ligne dans un fichier lu tôt (par exemple un 00-ioncube.ini) pour que le Loader s’initialise avant les autres extensions.
Redémarre le runtime PHP. Redémarre PHP-FPM, ton serveur web (Apache/Nginx), ou relance simplement la CLI — selon ce qui exécute ton application. Un processus de longue durée conserve l’ancienne configuration jusqu’à son redémarrage.

Verify

Confirme que le Loader est actif avant d’essayer de charger NextPDF.

D’abord, examine la bannière de version de PHP. Lorsque le Loader est installé, php -v ajoute une ligne qui le nomme :

php -v

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

La mention « with the ionCube PHP Loader » est le signal que le Loader est actif pour ce runtime. Pour un déploiement web (FPM / mod_php), la bannière de la CLI ne suffit pas — ce runtime peut utiliser un php.ini différent. Confirme le runtime web avec un petit script servi par le serveur 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.

Enfin, confirme qu’une classe premium de NextPDF se charge réellement via l’autoloader de Composer. Cela prouve que le code encodé s’exécute de bout en bout :

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

Si php -v nomme le Loader, que le phpinfo() web affiche la section ionCube et que la classe premium se résout, le Loader est correctement configuré.

Placement de la licence (la version Pro payante encodée avec ionCube)

ionCube utilise un modèle de licence simple : le code encodé recherche un fichier de licence à l’exécution et refuse de s’exécuter lorsque le fichier est manquant, illisible ou expiré. Cela s’applique à la version Pro payante encodée avec ionCube — pour celle-ci, tu places le fichier de licence fourni par ton achat à un emplacement où le runtime peut le trouver.

Ce mécanisme de fichier de licence ionCube est propre à la version encodée avec ionCube. La livraison officielle de NextPDF Enterprise n’est pas présumée encodée avec ionCube ici ; son empaquetage et la gestion de sa licence sont régis par tes conditions de licence — voir Licence et activation.

Les chemins exacts dépendent de l’environnement, alors reste général :

Place le fichier de licence à l’emplacement indiqué par les instructions de livraison de ton NextPDF — généralement à côté du paquet encodé ou dans un répertoire que l’application peut lire. Assure-toi que l’utilisateur du processus PHP dispose de la permission de lecture.
Ne renomme pas le fichier sauf si tes instructions le demandent ; le loader recherche un nom précis.
Dans les conteneurs et sur les déploiements en lecture seule, monte ou copie le fichier de licence dans l’image ou dans un chemin accessible en écriture et en lecture que le runtime voit (voir Docker et conteneurs).

Le fichier de licence régit l’activation au niveau du runtime ; il est distinct de la licence au niveau de l’application qui sélectionne ton édition et tes fonctionnalités. Pour les conditions, les durées et ce à quoi ton abonnement te donne droit, voir Licence et activation et ton contrat de licence — cette page ne définit pas les conditions de licence.

Troubleshooting

« Loader not installed » / « Failed loading … ioncube_loader »

Le Loader n’est pas actif dans le runtime qui a exécuté le code, ou le chemin est incorrect. Revérifie que la ligne zend_extension pointe vers un fichier existant avec un chemin absolu, que tu as redémarré le runtime, et que tu as vérifié le même runtime (CLI vs FPM) avec php -v / phpinfo(). Un message Failed loading signifie généralement que le fichier existe mais ne correspond pas à la version de PHP (voir le point suivant).

Non-correspondance de version de PHP, de NTS/ZTS ou d’architecture

Un Loader compilé pour une autre version de PHP, un autre mode de sûreté des threads ou une autre architecture ne se chargera pas. Confirme PHP Version, Thread Safety et Architecture à partir de php -i, puis installe le fichier du Loader pour PHP 8.4 avec le mode NTS/ZTS et l’architecture (bitness) correspondants. Le suffixe 8.4 vs 8.4_ts (ou _ts.dll) est le sélecteur de sûreté des threads — utiliser le mauvais est une erreur fréquente.

Ordre de chargement du Loader

Le Loader ionCube doit être un zend_extension et devrait s’initialiser avant les autres extensions. Si tu vois des avertissements indiquant que le Loader se charge après d’autres extensions, déplace sa ligne zend_extension plus haut — ou, avec une organisation conf.d, donne à son fichier d’inclusion un nom qui se trie en premier (par exemple 00-ioncube.ini).

La CLI, FPM et le serveur web utilisent des fichiers php.ini différents

PHP charge souvent un php.ini différent pour la CLI et pour PHP-FPM ou mod_php. Ne configurer que la CLI laisse le runtime web sans le Loader (ou inversement). Exécute php --ini pour voir quel fichier la CLI utilise, et examine la ligne Loaded Configuration File dans la sortie du phpinfo() web. Ajoute la ligne zend_extension à chaque php.ini qui exécute NextPDF, et redémarre chaque runtime.

Fichier de licence introuvable ou expiré

Pour la version Pro payante encodée avec ionCube, un fichier de licence manquant, illisible ou expiré empêche le code encodé de s’exécuter. Vérifie que le fichier se trouve à l’emplacement attendu, que l’utilisateur du processus PHP peut le lire, et qu’il n’a pas expiré. Pour les questions de renouvellement et de conditions, voir Licence et activation et ton contrat de licence.

Interactions avec OPcache

OPcache met en cache les scripts compilés, mais les fichiers encodés avec ionCube sont décodés par le Loader à l’exécution. Si tu as modifié le Loader ou sa configuration et que le runtime se comporte encore comme s’il était absent, redémarre le runtime PHP (ce qui vide OPcache) plutôt que de compter sur un rechargement à chaud. Garde le zend_extension ionCube enregistré pour qu’il se charge avant OPcache ; les deux coexistent, et php -v devrait les lister tous les deux.

Docker et conteneurs

Dans un déploiement conteneurisé, installe le Loader dans l’image, et assure-toi qu’il correspond à la version de PHP du conteneur — pas à celle de ton hôte. L’image de base fixe la version de PHP, le système d’exploitation, l’architecture et le mode de sûreté des threads, alors télécharge le bundle du Loader correspondant à ces valeurs.

Une construction d’image typique :

Pars d’une image de base PHP 8.4 (note si elle est NTS ou ZTS — les tags officiels php:8.4-cli / 8.4-fpm / 8.4-apache sont NTS, tandis que les tags contenant zts sont thread-safe ; choisis le Loader en conséquence).
Ajoute le fichier du Loader ionCube correspondant dans le extension_dir de l’image.
Écris la ligne zend_extension=... dans le php.ini de l’image (ou un include conf.d).
Pour la version Pro payante encodée avec ionCube, fournis le fichier de licence en le copiant dans l’image ou en le montant à l’exécution dans un chemin que le conteneur peut lire.

Comme le Loader est intégré à l’image, le même conteneur s’exécute à l’identique partout. Si tu mets plus tard à niveau la version de PHP de l’image de base, remplace le fichier du Loader par la version qui correspond au nouveau runtime.