How to Install the ionCube Loader on AlmaLinux 9 and Rocky Linux 9
Install the ionCube Loader on AlmaLinux 9, Rocky Linux 9 or CentOS Stream 9 so PHP can run ionCube-encoded applications, and verify that PHP-FPM and the CLI load it.
The ionCube Loader is a free PHP extension that lets PHP run files protected with the commercial ionCube Encoder. Many paid PHP applications, billing systems and plugins ship encoded and refuse to start without it. This guide installs the Loader on AlmaLinux 9, Rocky Linux 9 and CentOS Stream 9 with PHP from the distribution's AppStream repository, for both PHP-FPM and the command line.
CentOS 6 reached end of life in November 2020 and CentOS 7 in June 2024, so neither receives security fixes any more. AlmaLinux 9 and Rocky Linux 9 are the drop-in replacements, and the steps below are written for them.
Requirements
- A server running AlmaLinux 9, Rocky Linux 9 or CentOS Stream 9 on x86-64 or ARM64 (aarch64).
- A user with
sudorights. - A working web server with PHP, or permission to install PHP in the next step.
- A PHP version that ionCube provides a Loader for. This matters on the RHEL 9 family: see below.
Step 1: Use a PHP version the Loader supports
ionCube never released a Loader for PHP 8.0. Support went from PHP 7.4 straight to 8.1, and current Loader releases cover PHP 8.1 through 8.5. The default php package on the RHEL 9 family is PHP 8.0, so a plain dnf install php gives you a version that cannot load ionCube at all. Switch to a newer AppStream module stream first.
Check which version you have and which streams your release offers:
php -v
sudo dnf module list php
If PHP is not installed yet, enable a stream and install it. PHP 8.3 is used here; pick the newest stream your application's vendor supports.
sudo dnf module enable php:8.3
sudo dnf install php php-fpm php-cli
If PHP 8.0 is already installed, switch streams instead:
sudo dnf module reset php
sudo dnf module enable php:8.3
sudo dnf distro-sync
Note the minor version (for example 8.3), the extension directory and the directory PHP scans for extra ini files. You need all three later.
php -r 'echo PHP_MAJOR_VERSION, ".", PHP_MINOR_VERSION, PHP_EOL;'
php -i | grep -E '^extension_dir|Scan this dir'
On the RHEL 9 family the extension directory is /usr/lib64/php/modules and the scan directory is /etc/php.d. The distribution's PHP is a non-thread-safe build, so you need the regular loader file, not the one ending in _ts.so.
Step 2: Download and unpack the Loader
ionCube publishes one archive per platform that contains loader files for every supported PHP version. Download the one that matches your CPU architecture (uname -m) into a temporary directory, not into your web root.
For x86-64:
cd /tmp
curl -fsSLO https://downloads.ioncube.com/loader_downloads/ioncube_loaders_lin_x86-64.tar.gz
tar -xzf ioncube_loaders_lin_x86-64.tar.gz
For ARM64:
cd /tmp
curl -fsSLO https://downloads.ioncube.com/loader_downloads/ioncube_loaders_lin_aarch64.tar.gz
tar -xzf ioncube_loaders_lin_aarch64.tar.gz
The archive unpacks to a directory named ioncube. List it to see the available loaders:
ls /tmp/ioncube
Files are named after the PHP version, for example ioncube_loader_lin_8.3.so.
Step 3: Install the loader file
Copy the file that matches your PHP minor version into the PHP extension directory, then reset its SELinux label so PHP-FPM is allowed to load it:
sudo cp /tmp/ioncube/ioncube_loader_lin_8.3.so /usr/lib64/php/modules/
sudo chmod 755 /usr/lib64/php/modules/ioncube_loader_lin_8.3.so
sudo restorecon -v /usr/lib64/php/modules/ioncube_loader_lin_8.3.so
Step 4: Enable the Loader in PHP
The ionCube Loader is a Zend extension and has to be loaded before any other Zend extension, including OPcache. The ini files in /etc/php.d are read in alphabetical order and OPcache is configured in 10-opcache.ini, so give the ionCube file a name that sorts first:
echo 'zend_extension = /usr/lib64/php/modules/ioncube_loader_lin_8.3.so' | sudo tee /etc/php.d/00-ioncube.ini
Restart PHP-FPM so the web side picks up the change. On the RHEL 9 family both Apache and Nginx run PHP through PHP-FPM by default.
sudo systemctl restart php-fpm
If your server runs PHP inside Apache with mod_php from a third-party repository, restart httpd instead.
Step 5: Verify the installation
Check the command-line PHP first:
php -v
The output must contain a line that starts with with the ionCube PHP Loader, followed by the Loader version. Confirm that it is listed among the Zend extensions as well:
php -m | grep -i ioncube
The CLI and PHP-FPM read the same /etc/php.d directory on these systems, but check the web side too, because that is what your application uses. Create a temporary file in your document root:
echo '<?php phpinfo();' | sudo tee /var/www/html/info.php
Open http://203.0.113.10/info.php in a browser and look for the ionCube Loader line in the Zend Engine box near the top. Delete the file immediately afterwards, because it exposes your full PHP configuration:
sudo rm /var/www/html/info.php
Finally remove the downloaded files:
rm -rf /tmp/ioncube /tmp/ioncube_loaders_lin_*.tar.gz
Keeping the Loader up to date
The Loader is not managed by dnf, so system updates will not refresh it. Two events require action on your side:
- A new Loader release. Repeat steps 2 and 3 to overwrite the
.sofile and restart PHP-FPM. Release notes are published on the ionCube Loader download page. - A PHP minor version change (for example 8.3 to 8.4). Each loader file works with exactly one PHP minor version. Copy the new file, update the path in
/etc/php.d/00-ioncube.iniand restart PHP-FPM. Until you do, PHP logs a startup error and encoded applications stop working.
Troubleshooting
- The Loader does not show up in
php -v. Runphp --iniand confirm that/etc/php.d/00-ioncube.iniis in the list of parsed files, and that the path in it matches the file you copied. - PHP reports that the ionCube Loader must be loaded before other Zend extensions. Another ini file with a
zend_extensionline sorts ahead of yours. Rename the ionCube file so it comes first. - The CLI works but the website does not. Restart
php-fpm, then check/var/log/php-fpm/error.logandsudo ausearch -m avc -ts recentfor SELinux denials. Runningrestoreconon the loader file fixes a wrong label. - The application says the file was encoded for a different PHP version. That is a limit of the encoded files, not of the Loader. Ask the vendor for a build that matches your PHP version, or install the PHP version they support.
Frequently asked questions
Is the ionCube Loader free?
Yes. The Loader that runs encoded files is free to download and use. Only the Encoder, the tool that developers use to protect their code, is a paid product.
Can I use the ionCube Loader Wizard instead?
ionCube also offers a Loader Wizard, a PHP script you upload to your site that tells you which loader file and ini line your server needs. It is useful on shared hosting where you cannot inspect the system. On your own server the manual steps above are quicker, and if you do use the wizard, delete it from the web root when you are done.
Does ionCube work together with OPcache?
Yes, both can be active at the same time. The only requirement is the load order: the ionCube zend_extension line has to be processed before the OPcache one, which the 00- file name prefix takes care of.
Why can't I stay on the default PHP 8.0 package?
There is no ionCube Loader for PHP 8.0, and upstream PHP stopped supporting 8.0 in November 2023. Applications encoded for PHP 7.4 will not run on it either, so the practical choice is a PHP 8.1 or newer stream together with an application build encoded for that version.