How to Set a Different PHP Version for a Subfolder in cPanel

You have a main website on one PHP version and an application in a sub-folder that needs a different one. A common example is a new app that requires PHP 8.3 or newer, sitting inside a site that still runs older code. cPanel’s MultiPHP Manager assigns a version per document root, so it does not configure an arbitrary sub-folder on its own. cPanel documents a method for a sub-folder, a handler line in an .htaccess file in that folder, but only for particular setups: it needs the suPHP handler, it does not work with PHP-FPM, and cPanel warns against using it on sites that use PHP Selector. This guide shows that method, the situations where it does not apply, and what I found when my host used CloudLinux’s PHP Selector.

Before you start, it helps to know which PHP setting wins on cPanel, because a sub-folder setting only works if nothing stronger overrides it.

The documented method

cPanel has an article titled “How to set a different PHP version per directory”. Its steps are:

1. Open a command line as the cPanel user (SSH, or Terminal in cPanel).
2. Check whether the folder already has an .htaccess file. If it does, back it up and add the lines to it. Create a new file only if there is none.
3. Add these lines, replacing the digit after php8 with the minor version you want (for example ea-php84 for PHP 8.4):

<IfModule mime_module>
  AddHandler application/x-httpd-ea-php84 .php .php8 .phtml
</IfModule>

If you prefer the File Manager to a terminal, you can create the same file there. Whichever way you create it, the file goes in the sub-folder itself, not in the site’s main folder.

When this method does not work

The same cPanel article carries two warnings at the top:

• It only applies if you are using the suPHP handler, and it will not work with PHP-FPM. In MultiPHP Manager the PHP-FPM column shows whether a domain uses FPM. If it does, handler lines in .htaccess may be ignored.
• Sites using PHP Selector should not use this procedure. PHP Selector is the CloudLinux “Select PHP Version” tool. If your domain uses it, the ea-php handler above is not the one to use. Having the Select PHP Version icon in cPanel is a hint that you may be on such a setup, so confirm with your host.

Whether your sub-folder file wins also depends on the rest of the server’s setup. On LiteSpeed with CloudLinux, for example, the documented order depends on CageFS and on how PHP Selector is set. If a folder keeps the wrong version, work through the checks in the priority guide.

What happened on my host (PHP Selector)

My account uses PHP Selector, which fits the second warning. With the ea-php84 handler in the sub-folder’s .htaccess, the folder returned 403 Forbidden. With an alt-php84 handler, it worked:

<IfModule mime_module>
  AddHandler application/x-httpd-alt-php84 .php .php8 .phtml
</IfModule>

I did not find this alt-php line in cPanel’s own article, so I am describing what worked on one account, not documented behaviour. Handler names depend on how the host built the server (ea-php for cPanel’s EasyApache packages, alt-php for CloudLinux’s alternative packages, and LiteSpeed setups can use different names again). Ask your host for the exact handler name rather than guessing, because a wrong name can produce an error page.

If your account uses PHP Selector, cPanel’s article on using MultiPHP Manager with PHP Selector says Selector versions can be set per directory on the lsapi or suPHP handlers by using the command line, and points to CloudLinux’s documentation for the steps. It does not cover them, and I have not tried that method.

Check that it worked

1. Put a one-line file in the sub-folder:

   <?php echo PHP_VERSION;

   Open it in a browser, check the version, and delete the file straight away.

2. Do the same in the main site’s folder to confirm the main site did not change.
3. Test the application itself, not only the test file.

Things that can undo it

• Changing the version in MultiPHP Manager. cPanel says MultiPHP Manager updates the .htaccess in the domain’s document root and does not modify .htaccess files in directories that are not a document root. So your sub-folder file should not be rewritten by the panel, but it will not be updated either. If you later change versions on purpose, edit that file yourself.
• Plugins that rewrite .htaccess. When WordPress updates its own rewrite rules in the usual way (with insert_with_markers() and the WordPress marker), it replaces only the lines between # BEGIN WordPress and # END WordPress and keeps the rest of the file, so keep your handler lines outside that block. Some hosting guides report that security and caching plugins can regenerate the file and drop a handler block, which I have not verified. Keep a copy of your handler lines.
• Command-line PHP and cron jobs. The web version and the command-line version can differ. If a scheduled task must use the same version as the sub-folder app, ask your host for the correct versioned PHP binary path.

PHP settings for the sub-folder

If the app needs different limits from the main site (memory, upload size), those are separate from the version. Some hosting guides suggest putting a php.ini or .user.ini file in the sub-folder, but which file your host honours depends on its PHP setup, so check with your host first.

Checklist

1. Confirm with your host that the domain uses the suPHP handler, not PHP-FPM, and not PHP Selector, as cPanel’s article requires.
2. If the account uses PHP Selector, do not start from cPanel’s ea-php procedure. Ask your host for the supported per-directory method (cPanel’s article on MultiPHP Manager with PHP Selector mentions a command-line method for the lsapi or suPHP handlers, documented by CloudLinux).
3. Back up any existing .htaccess in the sub-folder, then add the handler your host documents (or create the file if there is none).
4. Test with a one-line version file in the sub-folder, then delete it.
5. Confirm the main site’s version did not change.
6. Keep a copy of the handler lines, in case something rewrites the file.

This is the setup behind the Composer error on a site that cPanel said was on PHP 8.4. For the follow-up problem, see what can make the old version come back, where the cause is not established.