Migrating a legacy Symfony project from PHP 7.4 to PHP 8.1

Why migrate

PHP 7.4 has been end-of-life for a long time now: no more security patches, no more official support. On a critical backend project running on OpenShift (Red Hat's Kubernetes-based platform for deploying and scaling containerized applications), staying on it was no longer tenable, neither from a security standpoint nor a performance one.

The main friction points

Strict typing and method signatures

PHP 8 is noticeably stricter about type consistency between parent and child classes (when a child class overrides a method from its parent, PHP now enforces that the parameter and return types stay compatible). Several legacy services had inconsistent signatures that passed silently under 7.4 but threw fatal errors under 8.1.

Function deprecations

Some long-standing functions (create_function, certain uses of each()) have been removed. A static code audit with PHPStan (a tool that analyzes PHP code for errors without actually running it) beforehand lets you list these cases before even touching the runtime version.

Implicit nullable types

PHP 8.1 forbids implicit nullable parameters without an explicit ?type declaration (the ? before a type means the parameter also accepts null, e.g. ?string). It's the kind of silent warning under 7.4 that becomes a blocker under 8.1 — a solid CI test suite (an automated pipeline that runs your tests on every commit) is essential to catch them all.

The migration strategy we chose

Full static audit with PHPStan at a high level to list incompatibilities before touching the runtime environment
Composer dependency upgrades (Composer is PHP's package manager, similar to npm for JavaScript) run in parallel, package by package, checking PHP 8.1 compatibility for each third-party library
Dedicated test environment on OpenShift with the new version, a duplicated Jenkins pipeline (Jenkins being the CI/CD server that automates our build, test, and deploy steps) to validate before switching over
Gradual rollout with the ability to quickly roll back to the previous build image

What surprised us the most

The real cost wasn't the PHP version change itself, but the technical debt that had to be dealt with at the same time: code that worked "by accident" under 7.4 and required genuine clarification of the contracts between classes.

Key takeaway

A major PHP version migration is never just a matter of changing a number in a config file. It's an opportunity to force a quality upgrade across the codebase — better to treat it as a project in its own right rather than a simple technical task.