PHP 8.1 to 8.2 or 8.3 — when and how should I migrate?
Decide which supported PHP branch to standardize on for apps and hosting stacks still pinned to PHP 8.1 after its end-of-life.
Blockers
- runtime/php-8-1 — EOL 2025-12-31
- runtime/php-8-2 — EOL 2026-12-31
- runtime/php-8-3 — EOL 2027-12-31
- PHP 8.2 deprecates dynamic properties, relative callables such as "self::method", utf8_encode()/utf8_decode(), and "${var}"/"${expr}" interpolation style; it also includes standard-library behavior changes.
- PHP 8.3 changes trait static property behavior, introduces DateError/DateException hierarchies in the Date extension, changes proc_get_status()/proc_close() behavior on POSIX, and deprecates get_class()/get_parent_class() without arguments plus assert_options() and assert.* INI settings.
Who this is for
- low-ops
- small-team
- enterprise
Candidates
Standardize on PHP 8.3
As of 2026-04-01, PHP 8.3 is the longer-lived supported branch in this decision set: active support ended on 2025-12-31 and security support continues until 2027-12-31. That gives one more year of supported life than PHP 8.2, whose security support ends on 2026-12-31. The PHP 8.2 to 8.3 migration guide describes only a few incompatibilities, which makes 8.3 the better default target once code is already being cleaned up for 8.2-era deprecations. Pricing is not set by upstream PHP; check official hosting docs for provider-specific image and plan costs.
When to choose
Use this for the default post-8.1 standard when you want the longest supported runway without jumping to a newer branch than the topic requires. It is the stronger choice if your dependencies and extensions already test cleanly on 8.2-level deprecations, because the remaining 8.3 delta is comparatively smaller.
Tradeoffs
Best support horizon of the two options and avoids doing another branch upgrade in the same year. The tradeoff is that you must absorb both the 8.1 to 8.2 deprecations and the smaller set of 8.3 behavior changes at once.
Cautions
From the official migration guides: 8.2 deprecates dynamic properties unless a class uses #[\AllowDynamicProperties], deprecates relative callables such as "self::method", and deprecates utf8_encode()/utf8_decode(). 8.3 changes trait static property behavior, introduces DateError/DateException hierarchies in the Date extension, changes proc_get_status()/proc_close() behavior on POSIX, and deprecates get_class()/get_parent_class() without arguments plus assert_options() and assert.* INI settings.
Standardize on PHP 8.2 temporarily
As of 2026-04-01, PHP 8.2 is still supported only for critical security fixes until 2026-12-31. It is the lower-risk branch if a host, distro package, extension set, or internal application has not yet been validated on 8.3-specific runtime changes. This can work as a short bridge off unsupported 8.1, but it has a short remaining support window and should not be treated as a long-term steady state. Pricing is not set by upstream PHP; check official hosting docs for provider-specific package availability and costs.
When to choose
Use this only when a blocker keeps you off 8.3 now, such as a hosting image gap, extension compatibility issue, or an application that depends on behavior changed again in 8.3. The decisive factor is whether reducing immediate migration risk is worth accepting another required upgrade before 2026-12-31.
Tradeoffs
Smallest immediate behavior jump from 8.1 and may align better with lagging platform support. The downside is that it is already in security-fixes-only status and forces another production upgrade on a near-term schedule.
Cautions
Do not mistake 8.2 for a fresh target branch: as of 2026-04-01 it is already past active support. The main cleanup items called out by the official 8.2 migration docs are dynamic property deprecations, deprecated relative callables, deprecated "${var}"/"${expr}" interpolation style, deprecated utf8_encode()/utf8_decode(), and several standard-library behavior changes such as ASCII-only case conversion and changed str_split("") behavior.
Try with your AI agent
$ npm install -g pocketlantern $ pocketlantern init # Restart Claude Code, Cursor, or your MCP client, then ask: # "PHP 8.1 to 8.2 or 8.3 — when and how should I migrate?"