De ionCube Loader instellen voor NextPDF premium-edities

In één oogopslag

Sommige NextPDF premium-distributies worden geleverd als ionCube-gecodeerde PHP, dus de bijbehorende ionCube Loader moet in uw PHP-runtime geïnstalleerd zijn voordat de code draait. Dit geldt voor:

De trial-builds van NextPDF Pro en Enterprise, en
De officiële (betaalde) build van NextPDF Pro.

Voor de officiële levering van NextPDF Enterprise hangt het verpakkingsmechanisme af van uw overeenkomst. Volg de leveringsinstructies in uw licentievoorwaarden in plaats van een specifieke runtime aan te nemen; zie Licenties en activering.

Deze pagina is een praktische installatiegids: wat ionCube is, hoe u de Loader installeert en verifieert, waar het licentiebestand komt voor de betaalde, ionCube-gecodeerde Pro-build, hoe u deze in containers draait, en hoe u de veelvoorkomende fouten oplost. De ondersteunde PHP-versie is 8.4, en de Loader die u installeert moet exact bij die runtime passen.

Wat ionCube is en waarom NextPDF het gebruikt

ionCube is een commerciële PHP-encoder, gekoppeld aan een gratis runtimecomponent die de ionCube Loader heet. De Loader is een PHP-extensie (Zend). Wanneer PHP start, stelt de Loader de gecodeerde bestanden in staat om te worden gedecodeerd en uitgevoerd; zonder de Loader kan een gecodeerd bestand niet draaien en meldt PHP in plaats daarvan een loader-fout.

NextPDF gebruikt ionCube-codering om de propriëtaire premium-broncode te beschermen en toch installeerbare PHP te leveren die u net als elk ander Composer-package implementeert en uitvoert. De codering verandert niets aan hoe u de bibliotheek aanroept — uw applicatie richt zich op dezelfde publieke contracten — ze voegt alleen de vereiste toe dat de Loader aanwezig is in de runtime.

Gebruik voor de Loader-downloads en de gezaghebbende, versiespecifieke instructies de leveranciersdocumentatie op ioncube.com (de ionCube Loader-documentatie en installatiegids). Deze pagina behandelt de NextPDF-specifieke installatie; de leverancier is de gezaghebbende bron voor de Loader zelf.

Vereisten

Installeer de ionCube Loader die op elke as bij uw PHP-runtime past. Een mismatch op één van deze assen is de meest voorkomende oorzaak van een storing:

As	Moet overeenkomen met
PHP-versie	8.4 (NextPDF premium vereist `>=8.4 <9.0`).
Besturingssysteem	Het OS waarop de Loader-bundel zich richt (Linux, Windows, macOS).
Architectuur	De CPU-architectuur van de host, doorgaans 64-bits (`x86-64` of `aarch64`).
Thread safety	Non-thread-safe (NTS) of thread-safe (ZTS), passend bij uw PHP-build.

Naast de Loader hebt u ook nodig:

Het NextPDF premium-package geïnstalleerd via Composer — nextpdf/pro, nextpdf/enterprise of het nextpdf/premium-metapackage.
Voor betaalde builds, uw licentiebestand. Zie voor de betaalde, ionCube-gecodeerde Pro-build Plaatsing van het licentiebestand hieronder.

Voer php -i uit (of roep phpinfo() aan) en bekijk de regels PHP Version, Architecture en Thread Safety om uw huidige build-waarden te lezen. Op de meeste CLI- en PHP-FPM-implementaties is thread safety uitgeschakeld (NTS); het klassieke Apache mod_php is op sommige platforms ZTS. Download de Loader-bundel voor die exacte waarden.

De Loader installeren

De onderstaande stappen vormen de algemene flow. Volg de ionCube Loader-documentatie op ioncube.com voor de exacte bestandsnamen en mappenstructuur van de huidige bundel.

Download de Loader-bundel die bij uw omgeving past (PHP 8.4, uw OS, architectuur en NTS/ZTS). De bundel bevat per PHP-versie en thread-safety- variant één loader-bestand.
Plaats het loader-bestand in de PHP-extensiemap. Gebruik de extension_dir die door php -i wordt gerapporteerd. Op Linux/macOS is het bestand ioncube_loader_<os>_8.4.so (gebruik ..._8.4_ts.so voor een ZTS-build); op Windows is het ioncube_loader_win_8.4.dll (of de ..._ts.dll ZTS-variant).
Registreer het in php.ini als een zend_extension. De ionCube Loader moet als zend_extension laden, niet als een gewone extension, en hij hoort vóór andere extensies te laden. Voeg één enkele regel toe, met een absoluut pad naar het loader-bestand:
```
zend_extension=/full/path/to/ioncube_loader_lin_8.4.so
```
Gebruik op Windows het volledige pad naar de .dll:
```
zend_extension="C:\php\ext\ioncube_loader_win_8.4.dll"
```
Als uw platform include-mappen in conf.d-stijl gebruikt, plaats deze regel dan in een bestand dat vroeg wordt ingelezen (bijvoorbeeld een 00-ioncube.ini), zodat de Loader vóór andere extensies initialiseert.
Herstart de PHP-runtime. Herstart PHP-FPM, uw webserver (Apache/Nginx), of voer simpelweg de CLI opnieuw uit — wat dan ook uw applicatie draait. Een langlopend proces behoudt de oude configuratie totdat het wordt herstart.

Verifiëren

Bevestig dat de Loader actief is voordat u NextPDF probeert te laden.

Controleer eerst de PHP-versiebanner. Wanneer de Loader is geïnstalleerd, voegt php -v een regel toe die hem noemt:

php -v

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

De zinsnede “with the ionCube PHP Loader” is het signaal dat de Loader actief is voor die runtime. Voor een web-implementatie (FPM / mod_php) is de CLI-banner niet voldoende — die runtime kan een andere php.ini gebruiken. Bevestig de web-runtime met een klein script dat door de webserver wordt geserveerd:

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

Bevestig ten slotte dat een NextPDF premium-class daadwerkelijk laadt via de autoloader van Composer. Dit bewijst dat de gecodeerde code van begin tot eind draait:

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

Als php -v de Loader noemt, de web-phpinfo() de ionCube-sectie toont en de premium-class wordt opgelost, is de Loader correct ingesteld.

Plaatsing van het licentiebestand (de betaalde, ionCube-gecodeerde Pro-build)

ionCube gebruikt een eenvoudig licentiemodel: de gecodeerde code controleert tijdens runtime op een licentiebestand en weigert te draaien wanneer het bestand ontbreekt, onleesbaar of verlopen is. Dit geldt voor de betaalde, ionCube-gecodeerde Pro-build — daarvoor plaatst u het licentiebestand dat uw aankoop verschaft op een plek waar de runtime het kan vinden.

Dit ionCube-licentiebestandsmechanisme is specifiek voor de ionCube-gecodeerde build. Van de officiële levering van NextPDF Enterprise wordt hier niet aangenomen dat deze ionCube-gecodeerd is; de verpakking en licentieafhandeling ervan worden bepaald door uw licentievoorwaarden — zie Licenties en activering.

Exacte paden zijn omgevingsspecifiek, dus we houden dit algemeen:

Plaats het licentiebestand op de locatie die uw NextPDF-leveringsinstructies aangeven — doorgaans naast het gecodeerde package of in een map die de applicatie kan lezen. Zorg ervoor dat de gebruiker van het PHP-proces leesrechten heeft.
Hernoem het bestand niet tenzij uw instructies dat aangeven; de loader zoekt naar een specifieke naam.
Mount of kopieer het licentiebestand in containers en op alleen-lezen- implementaties in de image of een beschrijfbaar, leesbaar pad dat de runtime ziet (zie Docker en containers).

Het licentiebestand regelt de activering op runtimeniveau; het staat los van de licentie op applicatieniveau die uw editie en functies selecteert. Zie voor de voorwaarden, looptijden en datgene waar uw abonnement recht op geeft Licenties en activering en uw licentieovereenkomst — deze pagina definieert geen licentievoorwaarden.

Probleemoplossing

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

De Loader is niet actief in de runtime die de code uitvoerde, of het pad is verkeerd. Controleer opnieuw of de zend_extension-regel verwijst naar een bestaand bestand met een absoluut pad, of u de runtime hebt herstart, en of u dezelfde runtime (CLI versus FPM) hebt geverifieerd met php -v / phpinfo(). Een Failed loading-melding betekent meestal dat het bestand bestaat maar niet bij de PHP-build past (zie het volgende punt).

Mismatch in PHP-versie, NTS/ZTS of architectuur

Een Loader die voor een andere PHP-versie, thread-safety-modus of architectuur is gebouwd, laadt niet. Bevestig PHP Version, Thread Safety en Architecture via php -i, en installeer dan het Loader-bestand voor PHP 8.4 met de passende NTS/ZTS en bitness. Het achtervoegsel 8.4 versus 8.4_ts (of _ts.dll) is de thread-safety-selector — de verkeerde gebruiken is een veel gemaakte fout.

Laadvolgorde van de Loader

De ionCube Loader moet een zend_extension zijn en hoort vóór andere extensies te initialiseren. Als u waarschuwingen ziet dat de Loader na andere extensies laadt, verplaats dan zijn zend_extension-regel naar voren — of geef, bij een conf.d-indeling, zijn include-bestand een naam die als eerste sorteert (bijvoorbeeld 00-ioncube.ini).

CLI, FPM en de webserver gebruiken verschillende php.ini-bestanden

PHP laadt voor de CLI vaak een andere php.ini dan voor PHP-FPM of mod_php. Alleen de CLI configureren laat de web-runtime zonder de Loader (of andersom). Voer php --ini uit om te zien welk bestand de CLI gebruikt, en controleer de regel Loaded Configuration File in de web-phpinfo()-uitvoer. Voeg de zend_extension-regel toe aan elke php.ini die NextPDF draait, en herstart elke runtime.

Licentiebestand niet gevonden of verlopen

Voor de betaalde, ionCube-gecodeerde Pro-build stopt een ontbrekend, onleesbaar of verlopen licentiebestand de uitvoering van de gecodeerde code. Controleer of het bestand op de verwachte locatie staat, of de gebruiker van het PHP-proces het kan lezen, en of het niet is verlopen. Zie voor vragen over verlenging en looptijd Licenties en activering en uw licentieovereenkomst.

Interacties met OPcache

OPcache cachet gecompileerde scripts, maar ionCube-gecodeerde bestanden worden tijdens runtime door de Loader gedecodeerd. Als u de Loader of de configuratie ervan hebt gewijzigd en de runtime zich nog steeds gedraagt alsof hij afwezig is, herstart dan de PHP-runtime (wat OPcache wist) in plaats van te vertrouwen op een hot reload. Houd de ionCube-zend_extension geregistreerd zodat hij vóór OPcache laadt; de twee bestaan naast elkaar, en php -v zou beide moeten vermelden.

Docker en containers

Installeer bij een gecontaineriseerde implementatie de Loader in de image, en zorg ervoor dat hij past bij de PHP-build van de container — niet die van uw host. De base-image legt de PHP-versie, het OS, de architectuur en de thread-safety-modus vast, dus download de Loader-bundel voor die waarden.

Een typische image-build:

Begin met een PHP 8.4-base-image (let op of het NTS of ZTS is — de officiële tags php:8.4-cli / 8.4-fpm / 8.4-apache zijn NTS, terwijl tags met zts thread-safe zijn; kies de Loader die daarbij past).
Voeg het passende ionCube Loader-bestand toe aan de extension_dir van de image.
Schrijf de regel zend_extension=... in de php.ini van de image (of een conf.d-include).
Verschaf voor de betaalde, ionCube-gecodeerde Pro-build het licentiebestand door het in de image te kopiëren of het tijdens runtime te mounten op een pad dat de container kan lezen.

Omdat de Loader in de image is ingebouwd, draait dezelfde container overal identiek. Als u later de PHP-versie van de base-image upgradet, vervang dan het Loader-bestand door de build die bij de nieuwe runtime past.