When migrating or deploying a Drupal 10 website, administrators may encounter a PHP compatibility error even though the hosting control panel indicates that the domain is already configured to use a supported PHP version.

A common example is the following message:

Composer detected issues in your platform: Your Composer dependencies require a PHP version ">= 8.3.0".

The error may appear even when cPanel MultiPHP Manager shows PHP 8.4 assigned to the domain. At first glance, this appears to be a Drupal issue. In reality, the problem is often related to how the hosting environment is applying PHP version settings.

Understanding the issue

Drupal does not check the PHP version selected in cPanel. Instead, it checks the PHP version that is actually executing the request.

This distinction is important because a hosting account may display one PHP version in the control panel while the web server continues to process requests using another version.

For example:

Component Reported PHP Version
cPanel MultiPHP Manager PHP 8.4
Drupal Runtime Check PHP version unsupported
Actual Web Server Runtime PHP 5.6

In this situation, Drupal is behaving correctly because it only evaluates the active runtime environment.

Why the PHP version in cPanel may not match the active PHP version

Several configuration layers can influence which PHP version is ultimately used by a website:

  • cPanel MultiPHP Manager
  • PHP-FPM configuration
  • Apache handlers
  • FastCGI handlers
  • Virtual host configuration
  • Account-level overrides
  • Server-level overrides
  • Legacy hosting configurations
  • Directory-specific .htaccess directives

If any of these components are misconfigured or conflict with one another, the domain may execute under a different PHP version than the one selected in cPanel.

Common causes

Legacy PHP handlers

Older websites often contain PHP handlers added years ago and forgotten.

Examples include:

AddHandler application/x-httpd-ea-php56 .php .php5 .phtml

or:

AddHandler application/x-httpd-ea-php74 .php

These directives can override the PHP version selected through the hosting control panel.

Conflicting PHP handlers

Sometimes multiple handlers are present in the same .htaccess file:

AddHandler application/x-httpd-ea-php56 .php .php5 .phtml
AddHandler application/x-httpd-ea-php84 .php .php8 .phtml

This is not recommended and can lead to inconsistent behavior. Only one handler should manage PHP file execution.

Legacy hosting migrations

Websites that have been transferred between multiple hosting providers over several years may inherit outdated configuration directives from previous environments.

Examples include:

  • Legacy cPanel configurations
  • Kloxo-related settings
  • Deprecated PHP directives
  • Historical workarounds
  • Obsolete Apache handlers

These configurations may continue affecting the website long after the original hosting environment has been retired.

PHP-FPM configuration

In some hosting environments, PHP-FPM may override or ignore .htaccess-based PHP assignments. As a result, the PHP version displayed in cPanel may differ from the PHP version actively serving requests.

Temporary workaround using a PHP handler

If the hosting provider confirms that PHP 8.4 is installed but the domain continues to execute using an older PHP version, a temporary workaround may be to explicitly define the PHP handler in the website’s .htaccess file.

Example:

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

The directive should generally be placed near the beginning of the .htaccess file before application-specific rewrite rules.

After adding the handler, verify that the website is now executing under the expected PHP version. If the PHP version mismatch disappears and Drupal loads successfully, this confirms that the required PHP version exists on the server but was not being applied automatically to the domain.

The exact handler name may vary depending on the hosting provider’s configuration.

Why the workaround should not be the long-term solution

Although adding a PHP handler directly to .htaccess may resolve the issue immediately, it is usually considered a workaround rather than a permanent solution.

In a properly configured cPanel environment, PHP version management should normally be handled through:

  • MultiPHP Manager
  • PHP-FPM configuration
  • Server-level PHP settings

rather than application-specific .htaccess modifications.

If a manual handler is required for the website to function, it may indicate an underlying configuration issue that should be reviewed by the hosting provider.

Considerations for Drupal websites

Drupal includes its own .htaccess file as part of Drupal core.

While Drupal updates do not automatically overwrite local customizations, administrators frequently review and merge core file changes during major and minor upgrades.

Adding custom PHP handlers to Drupal’s .htaccess file introduces an additional maintenance requirement.

Future migrations, upgrades, and troubleshooting activities must take these modifications into account.

For this reason, it is generally preferable to resolve PHP version assignment issues at the hosting configuration level whenever possible.

Composer and Drupal updates

A common question is whether Composer operations can overwrite custom .htaccess modifications.

Commands such as:

composer install
composer update
composer require
composer remove

They do not normally modify .htaccess files. However, Drupal core updates may include updated versions of core files, including .htaccess.

Administrators should therefore document any custom modifications and review them during future upgrade activities.

Questions to ask your hosting provider

If a website only functions after manually adding a PHP handler, consider asking the hosting provider the following questions:

  • Why is the PHP version selected in cPanel not being applied to the domain?
  • Is PHP-FPM overriding the cPanel PHP configuration?
  • Are there any account-level or server-level settings affecting PHP version selection?
  • Will future PHP version changes made through cPanel take effect automatically?
  • Is there a permanent configuration change that eliminates the need for a custom .htaccess handler?

These questions can help identify the root cause and determine whether the issue is account-specific or related to the hosting environment itself.

Recommended best practices

When deploying Drupal 10 or other modern PHP applications:

  • Verify the active PHP runtime after every migration or server transfer.
  • Review .htaccess files for legacy PHP handlers.
  • Remove obsolete hosting-specific directives when appropriate.
  • Keep PHP version management centralized through the hosting control panel.
  • Document any temporary workarounds implemented during troubleshooting.
  • Confirm that PHP-FPM and MultiPHP Manager are using the same PHP version.
  • Test application compatibility after every PHP version change.

Conclusion

When Drupal 10 reports that PHP 8.3 or higher is required even though cPanel is configured for PHP 8.4, the issue is often not Drupal itself.

The more common cause is a mismatch between the PHP version selected in the hosting control panel and the PHP version actually executing requests.

Legacy handlers, PHP-FPM configuration, account-level overrides, and historical hosting migrations can all contribute to this situation.

While manually defining a PHP handler in .htaccess may provide an effective short-term solution, the preferred long-term approach is to ensure that PHP version management is handled correctly through the hosting environment so that future upgrades, migrations, and maintenance activities remain straightforward and predictable.