A Loader file is required to read PHP scripts encoded with the ionCube Encoder. There are two ways to use this file, requiring different installation methods: run-time Loading and via the php.ini file.

Explanation of terminology

The Loader is a .dll file or .so file (depending on the server's operating system) which PHP uses to decode scripts encoded with the ionCube Encoder. PHP has the ability to open .dll (or .so) files at the moment a script is run. The dl function in PHP is used for this purpose. This mechanism, when used to launch the ionCube Loader, is called run-time loading.

When the web server first launches PHP, a configuration file called php.ini is read. It is possible to add a line to this file to instruct PHP to load the ionCube Loader.

We shall explain how to install Loaders using both of these methods in the following sections.

Run-time Loading Installation

The run-time loading method is the easiest way to run encoded files, and lets encoded files locate and install the correct Loader when needed.

Provided that run-time loading is supported on the target system, encoded scripts and Loaders can be bundled together without the user having to install any Loader or update their system configuration, and without having to know about the PHP version or operating system used.

For run-time loading to work, a directory called 'ioncube' containing the Loaders should be placed in or above the top directory of encoded files. For example, if you have encoded files in or below '/var/www/htdocs/', you might place the 'ioncube' directory in '/var/www/htdocs' or '/var/www'. If you have an application or library to distribute, you could place the ioncube directory within the top directory

Troubleshooting Run-time Loading

If encoded files fail to run with run-time loading, you can test this by using the helper PHP script 'ioncube-loader-helper.php' that's included in the Loader download archive.

1. Copy the 'ioncube-loader-helper.php' and 'ioncube-encoded-file.php' PHP scripts to a directory where you expect encoded files to be working.
2. Access the 'ioncube-loader-helper.php' script from a web server or with a PHP cli or cgi executable.
3. Choose the 'Run-time Loading Compatibility Test' option.
4. The script will try to locate and install the required Loader, and will produce output as it runs.
5. Once complete the script will either report that run-time loading is working, will provide instructions for how to correct any issue with the server configuration, or will report that Loaders must be installed in the php.ini file.

Using the ionCube Install Assistant

Installing in the php.ini file is also simple, and offers the best performance for encoded scripts. It is also required for systems that use safe mode, or if PHP has been built with thread support, e.g. on Windows.

The 'php.ini Install Assistant' link on the installation helper PHP script is provided to assist with this. Access the script from a web server or a PHP cli or cgi executable and it should tell you which Loader to install, which file to edit and what you need to add (it's just a one line change).

If you wish to install without using the assistant script then please read the following section.

Manual Installation in the php.ini File

Before installing, you need to know:

1. Which operating system you are using.
2. Which PHP version you are using.
3. Is your PHP build threaded or not?
4. Where your php.ini file is.

The 'Server System Information' link in the helper script will give you the required information.

Example

Suppose the following information is contained in the sysinfo.php script output:

This shows that:

1. The system is Linux
2. PHP is PHP 4.3.0
3. PHP is not threaded (thread safety disabled)
4. The php.ini file is in /usr/local/lib

Using this information we may install the Loaders. The method depends on whether your server is running Unix (e.g. Linux) or Windows.

Installation on a Unix Server

If your PHP is not threaded you need a Loader called:

If your PHP is threaded you need a Loader called:

<os type> will be 'lin' for Intel Linux, 'fre' for FreeBSD, 'sun' for Sparc Solaris, 'ope' for OpenBSD, 'dar' for OSX and 'net' for NetBSD.

<php flavour> will be 4.0, 4.1, 4.2 or 4.3 - i.e the first 2 digits of your PHP version.

Edit your php.ini file and for non-threaded PHP add:

and for threaded PHP add:

Replace <os type> and <php flavour> with whatever is right for your system, and <path> with the path to where the Loader is installed, e.g. /usr/local/ioncube

If there are other zend_extension entries in the php.ini file place this new entry before the existing entries.

For example, with Linux running PHP 4.1.2 and Apache 1, you might add:

For FreeBSD running threaded PHP 4.3.1 with Apache 2, you might add:

Installation on a Windows Server

You need a Loader called

<php flavour> will be 4.1, 4.2 or 4.3 - i.e the first 2 digits of your PHP version.

Edit your php.ini file and add:

where <drive> and <path> locate the Loader, and <php flavour> is whatever the correct value is for your system. If there are other zend_extension entries in the php.ini file place this new entry before the existing entries.

e.g.