CustomBuild PHP Versions: Switch PHP and Add Extensions Safely

CustomBuild compiles up to four PHP versions side by side and lets each domain pick one from the panel. As of DirectAdmin 1.711 the supported branches are PHP 8.2, 8.3, 8.4 and 8.5, and the build system carries a growing list of optional extensions that are toggled with ./build set rather than compiled by hand. Knowing which knob controls what saves a lot of time, because a manual edit to the wrong file is undone the next time ./build php runs.

Short answer: Assign versions to the four slots with ./build set phpN_release and ./build set phpN_mode, then run ./build php and ./build rewrite_confs; users pick a version per domain from the PHP Version Selector. Extensions such as pcntl, pdo_pgsql, mailparse and ioncube are switched on with ./build set <option> yes followed by a PHP rebuild, and anything CustomBuild does not offer goes in a custom/php/configure.phpNN file that survives updates.

The four PHP slots

Each slot is a pair of options in /usr/local/directadmin/custombuild/options.conf: phpN_release for the version and phpN_mode for the SAPI. Inspect the current state:

cd /usr/local/directadmin/custombuild
./build options | grep -E '^php[1-4]_(release|mode)'

Slot 1 is the default for new domains. A typical shared-hosting layout in 2026 is 8.4 as default with 8.3 and 8.2 available for older applications, and 8.5 in the fourth slot for customers who want to test it. Set it like this:

./build set php1_release 8.4
./build set php2_release 8.3
./build set php3_release 8.2
./build set php4_release 8.5
./build set php1_mode php-fpm
./build set php2_mode php-fpm
./build set php3_mode php-fpm
./build set php4_mode php-fpm
./build php
./build rewrite_confs

Use lsphp instead of php-fpm on OpenLiteSpeed or LiteSpeed Enterprise. The n argument tells CustomBuild not to prompt for the PHP mode between versions. The build compiles each version from source and takes several minutes per version; run it in screen.

PHP 8.2 reaches security end of life on 2026-12-31, so plan to retire the 8.2 slot before then. If you drop a version, set the slot to no and rebuild, then check that no domain still selects it: DirectAdmin falls back to slot 1 for those domains, but their php-fpm pool files linger until rewrite_confs.

Selecting a version per domain

Users choose a version in User Level → Domain Setup → domain → PHP Version Selector in the Evolution skin. The selection is stored in the user’s domain configuration under /usr/local/directadmin/data/users/<user>/domains/<domain>.conf as php1_select. Administrators can change it for a user without logging in as them by editing that value and rewriting the user’s configuration:

echo "action=rewrite&value=httpd&user=example" >> /usr/local/directadmin/data/task.queue

The task queue runs every minute from the dataskq cron entry, so allow up to sixty seconds.

Enabling extensions

Most extensions are compiled into the PHP binary and switched with options rather than installed as loadable modules. The ones added in recent releases are pcntl (1.704), and pdo_pgsql and mailparse (1.707). Turn them on and rebuild:

./build set php_pcntl yes
./build set php_pdo_pgsql yes
./build set php_mailparse yes
./build php_extensions

pcntl is worth a note. It lets PHP fork and handle signals, which queue workers and long-running CLI tools need, but it is also useful to attackers who obtain code execution. Enable it only where a customer genuinely needs it, and on shared servers keep it out of the web SAPI by listing its functions in disable_functions in the per-version php.ini while leaving the CLI binary unrestricted.

Long-standing options such as opcache, imap, xmlrpc and htscanner work the same way. Run ./build opt_help to see the full list for your CustomBuild version, because new toggles appear regularly and the names occasionally change.

For an extension that CustomBuild does not offer, add a custom configure file rather than editing the generated one. Copy the current script and append your flag:

mkdir -p custom/php
cp configure/php/configure.php84 custom/php/configure.php84
# edit custom/php/configure.php84 and add e.g. --with-ldap
./build php

The custom/ directory is respected across updates. Remember to repeat the change for each PHP version slot, since every version has its own configure script.

ionCube loader

The ionCube loader is a binary Zend extension distributed separately, and CustomBuild installs and wires it in for every enabled version:

./build set php_ioncube yes
./build php_ioncube

The loader is placed in the extension directory of each PHP version and referenced from a 10-directadmin.ini file in the version’s conf.d directory. ionCube publishes loaders for new PHP branches some weeks after PHP itself, so if ./build php_ioncube reports that no loader exists for 8.5, that is an upstream lag, not a build error. Do not copy a loader from another version; the ABI is different and PHP will refuse to start.

Common pitfall: editing the wrong php.ini

Each version has its own configuration: /usr/local/php84/lib/php.ini, /usr/local/php83/lib/php.ini and so on, with the FPM pool files under /usr/local/php84/etc/php-fpm.d/. Editing /etc/php.ini does nothing. After changing a php.ini, restart only the FPM service for that version:

systemctl restart php-fpm84

On LiteSpeed builds the change is picked up on the next lsphp process spawn, but a graceful restart with systemctl restart lsws makes it immediate.

Verify

Confirm each version reports the extensions you expect and that the loader is active:

for v in 82 83 84 85; do echo "== php$v"; /usr/local/php$v/bin/php -m | grep -Ei 'pcntl|pdo_pgsql|mailparse|ionCube'; done
/usr/local/php84/bin/php -v

The -v output should mention the ionCube loader on its second line when it is installed. Then create a phpinfo() file in a test domain, switch that domain between versions in the PHP Version Selector, and confirm the page reflects the change within a minute. If it does not, check /var/log/directadmin/errortaskq.log for a failed rewrite.

CustomBuild PHP versions at a glance

Official documentation: DirectAdmin documentation, Linux man pages.

Related guides: Choosing a VPS for a cPanel or DirectAdmin server in 2026 · Running Node.js and Python apps with Nginx Unit and per-user Redis on DirectAdmin · 503 Service Unavailable with PHP-FPM on DirectAdmin (and where the logs went after 1.689).

Frequently asked questions