How to Fix a Joomla Site That Breaks After a PHP Upgrade
If a Joomla site breaks immediately after changing PHP, treat the PHP change as the primary suspect until the logs prove otherwise. A blank page or HTTP 500 often comes from incompatible Joomla/extension code, a missing PHP module, a changed PHP configuration, or a different runtime being used by the web server. Preserve the evidence before replacing Joomla files or reinstalling extensions.
Capture the failure and restore service only with a known-good runtime
- Record the old and new PHP versions, exact change time, affected URLs, and visible HTTP/error message.
- Read PHP, PHP-FPM, web-server, and hosting logs for that timestamp.
- If the previous PHP version is still supported by the installed Joomla release and your host, switch back temporarily to confirm the PHP change is the trigger.
- Restore the previous PHP modules/configuration as well as the version when possible.
If returning to the previous supported runtime restores the site, keep it there while you prepare the software for the newer PHP version. Do not leave an unsupported PHP release in production as a permanent fix.
Confirm which PHP runtime and modules Joomla is actually using
Hosting panels can assign different PHP versions to the website, subdomains, command line, and cron jobs. Verify the web runtime serving the broken domain rather than relying on php -v. Check the database driver and required PHP modules after the switch; a host can provide a new PHP version with a different module set.
Also compare memory limits, disabled functions, timezone, upload/post limits, session handling, and PHP-FPM pool configuration if the error points there. A version switch can change more than the PHP executable.
Use the fatal error to identify incompatible code
Trace the first relevant fatal error or exception to its file, class, function, or package. Determine whether it belongs to Joomla core, a plugin, component, template override, library, or custom integration. Check the installed Joomla version against Joomla's official PHP requirements and the third-party product against its vendor's PHP support matrix.
For Joomla 6.x, current requirements list PHP 8.3.0 as supported/minimum and PHP 8.4 as recommended. That does not mean every third-party extension supports every PHP release Joomla supports. Update or replace incompatible code through the developer's supported path rather than editing vendor files blindly.
Build and test the corrected PHP environment on staging
- Clone the production site to staging.
- Apply Joomla and extension updates required to support the target PHP version.
- Switch staging to the target PHP runtime and confirm its required modules.
- Test Administrator, frontend, authentication, editing, forms, uploads, search, email, scheduled tasks, APIs, payments, and CLI jobs.
- Review logs for fatal errors, type errors, deprecations, missing modules, and memory/resource failures.
Do not suppress errors merely to make pages appear healthy. The purpose of staging is to remove the incompatibility before production is exposed to it.
Repeat the proven PHP change on production
Take a fresh files-and-database backup, document the working PHP configuration, and schedule a maintenance window. Switch production using the same PHP version/modules/settings proven on staging. Then run the acceptance checklist and verify scheduled/CLI jobs separately.
If production still fails, compare the production and staging PHP configuration and logs before changing Joomla. Differences in modules, filesystem paths, FPM pools, environment variables, web-server rules, or extension configuration often explain why an apparently identical PHP version behaves differently.
Need More Help with Joomla?
Still having trouble? Open a support ticket with QuantaCade Support and we'll be happy to help where we can.
Support priority is given to QuantaCade products, services, and customers. However, we're also happy to assist fellow Joomla users with general Joomla questions and troubleshooting when possible.
QuantaCade is an independent Joomla extension developer and is not official Joomla support. Some issues involving third-party extensions, hosting environments, server configurations, or other systems outside our development control may be beyond what we're able to resolve.