Set up the ionCube Loader for NextPDF premium editions

At a glance

Some NextPDF premium distributions ship as ionCube-encoded PHP, so the matching ionCube Loader must be installed in your PHP runtime before the code will run. This applies to:

The NextPDF Pro and Enterprise trial builds, and
The NextPDF Pro official (paid) build.

For NextPDF Enterprise official delivery, the packaging mechanism depends on your agreement. Follow the delivery instructions in your license terms rather than assuming a specific runtime; see Licensing and activation.

This page is a practical setup guide: what ionCube is, how to install and verify the Loader, where the license file goes for the paid, ionCube-encoded Pro build, how to run it in containers, and how to fix the common failures. The supported PHP version is 8.4, and the Loader you install must match that runtime exactly.

What ionCube is and why NextPDF uses it

ionCube is a commercial PHP encoder paired with a free runtime component called the ionCube Loader. The Loader is a PHP (Zend) extension. When PHP starts, the Loader allows the encoded files to be decoded and executed; without it, an encoded file cannot run and PHP reports a loader error instead.

NextPDF uses ionCube encoding to protect the proprietary premium source while still shipping installable PHP that you deploy and run like any other Composer package. The encoding does not change how you call the library — your application targets the same public contracts — it only adds the requirement that the Loader is present in the runtime.

For the Loader downloads and the authoritative, version-specific instructions, use the vendor documentation at ioncube.com (the ionCube Loader documentation and installation guide). This page covers the NextPDF-specific setup; the vendor is the source of truth for the Loader itself.

Requirements

Install the ionCube Loader that matches your PHP runtime on every axis. A mismatch on any one of these is the most common cause of failure:

Axis	Must match
PHP version	8.4 (NextPDF premium requires `>=8.4 <9.0`).
Operating system	The OS the Loader bundle targets (Linux, Windows, macOS).
Architecture	The CPU architecture of the host, typically 64-bit (`x86-64` or `aarch64`).
Thread safety	Non-thread-safe (NTS) or thread-safe (ZTS), matching your PHP build.

Beyond the Loader, you also need:

The NextPDF premium package installed via Composer — nextpdf/pro, nextpdf/enterprise, or the nextpdf/premium metapackage.
For paid builds, your license file. For the paid, ionCube-encoded Pro build, see License placement below.

To read your current build values, run php -i (or call phpinfo()) and check the PHP Version, Architecture, and Thread Safety lines. On most CLI and PHP-FPM deployments thread safety is disabled (NTS); classic Apache mod_php on some platforms is ZTS. Download the Loader bundle for those exact values.

Install the Loader

The steps below are the general flow. Defer to the ionCube Loader documentation on ioncube.com for the exact file names and directory layout of the current bundle.

Download the Loader bundle that matches your environment (PHP 8.4, your OS, architecture, and NTS/ZTS). The bundle contains one loader file per PHP version and thread-safety variant.
Place the loader file in the PHP extension directory. Use the extension_dir reported by php -i. On Linux/macOS the file is ioncube_loader_<os>_8.4.so (use ..._8.4_ts.so for a ZTS build); on Windows it is ioncube_loader_win_8.4.dll (or the ..._ts.dll ZTS variant).
Register it in php.ini as a zend_extension. The ionCube Loader must load as a zend_extension, not a plain extension, and it should load before other extensions. Add a single line, using an absolute path to the loader file:
```
zend_extension=/full/path/to/ioncube_loader_lin_8.4.so
```
On Windows, use the full path to the .dll:
```
zend_extension="C:\php\ext\ioncube_loader_win_8.4.dll"
```
If your platform uses conf.d-style include directories, place this line in a file that is read early (for example a 00-ioncube.ini) so the Loader initializes before other extensions.
Restart the PHP runtime. Restart PHP-FPM, your web server (Apache/Nginx), or simply re-run the CLI — whichever runs your application. A long-running process keeps the old configuration until it is restarted.

Verify

Confirm the Loader is active before you try to load NextPDF.

First, check the PHP version banner. When the Loader is installed, php -v appends a line that names it:

php -v

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

The phrase “with the ionCube PHP Loader” is the signal that the Loader is active for that runtime. For a web (FPM / mod_php) deployment, the CLI banner is not enough — that runtime can use a different php.ini. Confirm the web runtime with a small script served by the web server:

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

Finally, confirm that a NextPDF premium class actually loads through Composer’s autoloader. This proves the encoded code runs end to end:

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

If php -v names the Loader, the web phpinfo() shows the ionCube section, and the premium class resolves, the Loader is set up correctly.

License placement (the paid, ionCube-encoded Pro build)

ionCube uses a simple licensing model: the encoded code checks for a license file at runtime and refuses to run when the file is missing, unreadable, or expired. This applies to the paid, ionCube-encoded Pro build — for it, you place the license file your purchase provides where the runtime can find it.

This ionCube license-file mechanism is specific to the ionCube-encoded build. NextPDF Enterprise official delivery is not assumed to be ionCube-encoded here; its packaging and license handling are governed by your license terms — see Licensing and activation.

Exact paths are environment-specific, so keep this general:

Put the license file in the location your NextPDF delivery instructions specify — commonly alongside the encoded package or in a directory the application can read. Make sure the PHP process user has read permission.
Do not rename the file unless your instructions say to; the loader looks for a specific name.
In containers and on read-only deployments, mount or copy the license file into the image or a writable, readable path the runtime sees (see Docker and containers).

The license file governs activation at the runtime level; it is separate from the application-level license that selects your edition and features. For the terms, durations, and what your subscription entitles, see Licensing and activation and your license agreement — this page does not define license terms.

Troubleshooting

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

The Loader is not active in the runtime that ran the code, or the path is wrong. Re-check the zend_extension line points to an existing file with an absolute path, that you restarted the runtime, and that you verified the same runtime (CLI vs FPM) with php -v / phpinfo(). A Failed loading message usually means the file exists but does not match the PHP build (see the next item).

PHP version, NTS/ZTS, or architecture mismatch

A Loader built for a different PHP version, thread-safety mode, or architecture will not load. Confirm PHP Version, Thread Safety, and Architecture from php -i, then install the Loader file for PHP 8.4 with the matching NTS/ZTS and bitness. The 8.4 vs 8.4_ts (or _ts.dll) suffix is the thread-safety selector — using the wrong one is a frequent mistake.

Loader load order

The ionCube Loader must be a zend_extension and should initialize before other extensions. If you see warnings about the Loader loading after other extensions, move its zend_extension line earlier — or, with a conf.d layout, give its include file a name that sorts first (for example 00-ioncube.ini).

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

PHP commonly loads a different php.ini for the CLI than for PHP-FPM or mod_php. Configuring only the CLI leaves the web runtime without the Loader (or vice versa). Run php --ini to see which file the CLI uses, and check the Loaded Configuration File line in the web phpinfo() output. Add the zend_extension line to every php.ini that runs NextPDF, and restart each runtime.

License file not found or expired

For the paid, ionCube-encoded Pro build, a missing, unreadable, or expired license file stops the encoded code from running. Verify the file is in the expected location, that the PHP process user can read it, and that it has not expired. For renewal and term questions, see Licensing and activation and your license agreement.

OPcache interactions

OPcache caches compiled scripts, but ionCube-encoded files are decoded by the Loader at runtime. If you changed the Loader or its configuration and the runtime still behaves as if it is absent, restart the PHP runtime (which clears OPcache) rather than relying on a hot reload. Keep the ionCube zend_extension registered so it loads ahead of OPcache; the two coexist, and php -v should list both.

Docker and containers

In a containerized deployment, install the Loader in the image, and make sure it matches the container’s PHP build — not your host’s. The base image fixes the PHP version, OS, architecture, and thread-safety mode, so download the Loader bundle for those values.

A typical image build:

Start from a PHP 8.4 base image (note whether it is NTS or ZTS — the official php:8.4-cli / 8.4-fpm / 8.4-apache tags are NTS, while tags containing zts are thread-safe; pick the Loader to match).
Add the matching ionCube Loader file to the image’s extension_dir.
Write the zend_extension=... line into the image’s php.ini (or a conf.d include).
For the paid, ionCube-encoded Pro build, provide the license file by copying it into the image or mounting it at runtime into a path the container can read.

Because the Loader is built into the image, the same container runs identically everywhere. If you later upgrade the base image’s PHP, replace the Loader file with the build that matches the new runtime.