What Engineering Teams Should Consider When Modernizing a Legacy PHP Application

 

Every engineer who has worked with PHP long enough eventually inherits an older codebase. Maybe it is still on PHP 5 syntax patterns, maybe it predates Composer, maybe half the business logic lives inside view files. The instinct is often to rewrite it. The better instinct is to figure out whether a rewrite is actually the right call before starting one.

Rewriting is rarely the first move

A full rewrite is expensive, slow, and risky, because it freezes feature development while the team rebuilds something that already works, at least well enough to keep the business running. Before recommending a rewrite, it is worth separating three different problems that often get lumped together as "this codebase is old."

The code is outdated but stable. Old syntax, no type declarations, mixed logic and presentation, but it runs correctly and rarely breaks. This usually does not need a rewrite. It needs incremental modernization around the edges.

The code is fragile. Changes in one place break unrelated features, tests do not exist, and every deploy carries risk. This is a real problem, but the fix is often adding tests and refactoring hot paths, not rewriting everything at once.

The code cannot support what the business needs next. The architecture genuinely cannot handle a requirement that matters, such as scaling past current traffic or integrating with a system it was never designed to talk to. This is the case where a larger rewrite or a strangler pattern migration might actually be justified.

The strangler pattern beats a big rewrite

Instead of stopping feature work to rebuild everything, route new functionality through new code while the legacy application keeps running underneath it. Over time, more of the system moves to the new code path, and the legacy application shrinks until it can be retired safely. This approach lets the business keep shipping while the codebase improves, instead of asking stakeholders to accept months of no visible progress.

Upgrade PHP versions before anything else

If the application is running on an old PHP version, upgrading that first, even before any structural changes, usually pays off quickly. Newer PHP versions bring real performance improvements and security fixes, and staying on an unsupported version is a growing liability regardless of what else changes in the codebase.

Add tests around the code you are about to touch, not the whole codebase

Trying to write full test coverage for a legacy application before touching it is a good way to never touch it. A more realistic approach is writing tests specifically for the part of the code you are about to refactor, just enough to know that your change did not break existing behavior. Coverage grows naturally over time as more of the codebase gets touched this way.

Document what the code actually does before assuming what it should do

Legacy business logic often encodes decisions nobody remembers making. Before rewriting a piece of logic, it is worth confirming what it currently does in production, including the edge cases, rather than assuming the obvious behavior is the only behavior. Removing a rule that looks unnecessary can quietly break a workflow that a customer depends on.

The real goal is reducing risk, not modernizing for its own sake

Modernization should be justified by what it enables, whether that is faster feature delivery, fewer production incidents, or the ability to hire engineers who do not want to work in outdated patterns. Modernizing code that nobody plans to touch again is not a good use of time, even if it would be satisfying to clean up.