Migrating Magento 2 to PHP 8.3: Compatibility Issues and Fixes

Moving to a new PHP major version is one of those migrations that looks simple on paper — update the runtime, run the site — and then surfaces a dozen small breakages, almost all of them in third-party code rather than Magento core.

Confirm Your Magento Version Actually Supports PHP 8.3

This is the step people skip. Not every Magento 2.4.x release supports every PHP version — check the official compatibility matrix for your exact Magento version before switching anything. Running an unsupported combination can produce confusing, hard-to-diagnose errors that look like application bugs but are really just an unsupported runtime.

Sync Composer's Platform Config First

Before touching your actual PHP binary, make sure Composer knows what version you're targeting — mismatches here cause Composer to resolve dependencies for a PHP version you're not actually running:

composer config platform.php 8.3.0
composer update

Common Breakage: Deprecated Dynamic Properties

PHP 8.2 started deprecating dynamic properties (setting a property on a class that never declared it), and 8.3 continues enforcing this more strictly. Older third-party Magento extensions that rely on this pattern will throw deprecation warnings — and depending on your error reporting configuration, those can escalate into visible errors on the storefront.

Turn on full error reporting temporarily in a test environment to surface these before they hit production:

error_reporting(E_ALL);
ini_set('display_errors', 1);

If a third-party class is the source, the real fix belongs in that extension's code — either the vendor has released a compatible version, or the property needs to be explicitly declared:

class Something
{
    #[\AllowDynamicProperties]
    // ...
}

Treat this as a stopgap, not a permanent fix — it silences the warning without addressing the underlying code pattern.

Recompile Dependency Injection After Switching Runtimes

A PHP version change can affect compiled DI output in subtle ways. Always recompile after switching:

rm -rf generated/code/* generated/metadata/*
bin/magento setup:di:compile

Verify the Switch Actually Took Effect

It's easy to update php-fpm's config and still be running the old CLI binary for bin/magento commands, or vice versa — check both explicitly:

php -v
php-fpm8.3 -v

If bin/magento commands report a different version than what your web server is actually using, something in your PATH or service configuration wasn't fully switched over.

Test Third-Party Extensions Individually

Rather than upgrading everything and debugging a pile of simultaneous failures, test extensions one at a time if you can — disable everything non-essential, confirm core Magento works cleanly on 8.3, then re-enable extensions one by one and watch logs after each.

bin/magento module:disable Vendor_Extension
bin/magento cache:flush

Have a Rollback Plan

Keep the previous PHP version installed and available (not removed) until you've verified the new one under real traffic for a reasonable period. Rolling back a PHP-FPM pool config is fast; rolling back a codebase change made to work around a PHP 8.3 incompatibility is not.

Pre-Launch Checklist

1. Confirm your Magento version officially supports PHP 8.3.
2. Sync composer.json's platform.php to match.
3. Recompile DI (setup:di:compile) after the runtime switch.
4. Enable full error reporting in a test environment and browse the full storefront and admin to surface deprecation warnings.
5. Test third-party extensions individually rather than all at once.
6. Confirm both your web server and CLI are actually running the new version.
7. Keep the old PHP version available for rollback until you're confident in production.