How to Modernise a Legacy PHP Application Without Breaking It

01

A working application can still be hard to move

Imagine a PHP portal that has served the business for twelve years. Customers submit orders, staff review them and the system sends renewal reminders. It runs on one server and rarely causes a visible incident.

The problem appears when the hosting provider announces that the operating system must be upgraded. Nobody knows the exact PHP patch version, which extensions are installed, whether a scheduled task runs outside the application or why one directory needs unusual write permissions.

This is where legacy risk often hides. The code is only part of the application. Its real operating environment also includes PHP configuration, web server rules, database access, certificates, file storage, background jobs, email settings, system packages and network permissions.

If that environment exists only as the current server, the server has become undocumented source code. Replacing it while changing the PHP version and refactoring the application creates several possible causes for every failure.

A blank page could be a removed PHP feature, a missing extension, a permissions problem or an unhandled application error. Changing everything together makes diagnosis slower precisely when the business needs confidence.

02

Modernisation is controlled risk reduction

Modernisation is often presented as a visual transformation. A new framework, cloud hosting and a polished interface make an easy before and after story.

Those things may become useful, but they are not the first measure of success.

For the renewal portal, a better first outcome would be more modest. A second environment can be built from written instructions. The critical journeys have repeatable checks. A deployment has a rollback route. The team knows which PHP versions and dependencies are supported. Logs reveal failures before customers report them.

That is modernisation because it changes the application from something the business is afraid to touch into something it can operate deliberately.

The work should keep asking what behaviour must remain true, what is changing in this step, how success will be proved and how the change will be reversed if it fails. Those questions prevent a technical improvement from becoming an uncontrolled business experiment.

03

Begin with one critical business journey

Before listing packages or discussing frameworks, choose one journey that matters.

For our example, it could be: a customer submits a renewal, a staff member checks the details, the payment is recorded and a confirmation is sent.

Walk through the journey with the people who use it. Record the inputs, decisions, exceptions, documents, integrations and expected results. Ask what they check manually because they do not trust the screen. Ask which mistakes are recoverable and which would cause a customer or financial problem.

This gives the technical work a boundary. The team is not trying to understand every historical function before it can begin. It is protecting one complete piece of business behaviour and using that journey to reveal the systems around it.

It also finds requirements that code inspection misses. A developer may see that a status changes from pending to approved. An operations user knows that approvals received after 4pm must wait until the next working day. Both facts matter to a safe upgrade.

04

Inventory the runtime before changing it

The next job is to describe the environment closely enough to reproduce it.

Record the exact PHP version, not just PHP 7 or PHP 8. List installed extensions and relevant php.ini settings. Capture the web server version, enabled modules, virtual host rules and URL rewriting. Identify Composer dependencies, manually copied libraries and any application code edited directly on the server.

Then move beyond PHP. Find scheduled tasks, queue workers, file uploads, generated documents, email routes, database versions, external APIs, certificates, network rules and system packages. Check where secrets are stored and who controls the accounts needed to replace them.

Some discoveries will look untidy. That is useful evidence, not a reason to tidy them immediately.

Write the findings down as requirements for the current application. The document should distinguish confirmed facts from assumptions. If a library appears unused, mark it for investigation rather than quietly removing it during the first rebuild.

Current PHP releases receive two years of active support followed by two years of security fixes. An application on an older version may therefore be carrying known security and compatibility risk. That creates urgency, but urgency is not a licence to skip discovery.

05

Reproduce the old application first

Create a separate environment using the current code and, as closely as practical, the current PHP runtime.

This can feel like a backward step. Why spend time recreating the thing you intend to improve? Because it separates environment discovery from code change.

If the portal does not run in the faithful copy, the difference is likely to be in the configuration, infrastructure, permissions, data or undocumented dependency. You can solve that problem while the application code remains constant.

Once the same code completes the protected renewal journey in both places, you have a baseline. The business still has the existing production system, while the team has proved it can build another working environment.

Use representative but properly protected data. Production data should not be casually copied into a developer laptop or shared test service. Mask personal information where possible and preserve only the relationships and edge cases needed to test the behaviour.

The objective is reproducibility. A new environment should come from versioned configuration and a documented process, not from somebody remembering a sequence of clicks.

06

Protect behaviour with evidence

Legacy applications often have too few automated tests. Waiting for comprehensive coverage before making progress can turn into another form of paralysis.

Start with evidence around the critical journey.

Add a small set of characterisation tests that describe what the application does now, even when that behaviour is not ideal. A valid renewal creates the expected records. An expired account is rejected. A confirmation is sent once. A failed payment does not mark the renewal complete.

Combine those tests with practical smoke checks for login, permissions, scheduled work, file generation and the main integrations. Capture useful logs and error reporting. Record the queries or output used to reconcile important data before and after a change.

This is not a claim that the application is now fully tested. It is a safety net around the behaviour most likely to hurt the business if it changes unexpectedly.

The evidence also changes the conversation. Instead of asking whether the new environment feels fine, the team can compare specific outcomes and investigate a clear difference.

07

Put dependencies and configuration under control

Before upgrading PHP, reduce the number of invisible moving parts.

Confirm that the repository contains the code actually running in production. Move environment specific values out of source code. Document how secrets are supplied without committing them. Use Composer to manage PHP dependencies where practical, and keep a reviewed lock file so environments install known versions.

This stage may uncover a plugin copied into a folder, a production fix missing from Git or a library downloaded from a site that no longer exists. Do not hide those findings behind a clean new repository. Decide whether each dependency should be retained, replaced or removed, and preserve evidence of the decision.

Make small commits with focused changes. A commit that only normalises configuration is easier to review and reverse than one that also rewrites database access and changes the frontend.

The aim is not administrative neatness. Controlled dependencies make the same application more likely to behave the same way in testing, production and the next developer's environment.

08

Upgrade PHP as a separate workstream

Now create an environment with the target PHP version and keep the application code as stable as possible.

Use the official migration guide for each version crossed. PHP releases include new features, deprecations, changed defaults and incompatibilities that should be tested before a production switch. A static analysis tool can find some incompatible patterns, while the protected journeys and logs reveal behavioural differences.

For a very old application, several smaller version steps may be safer than one large leap. The right sequence depends on the starting version, available hosting, dependencies and how easily the team can run both environments. The important principle is that each step has a defined target and evidence.

When a dependency blocks the upgrade, treat it as its own decision. It may have a maintained version, a compatible replacement or a small boundary that can be rewritten without disturbing the rest of the application.

Do not mix cosmetic refactoring into compatibility changes. An old function can be ugly and still be understood. If it must change to run on the supported PHP version, make the smallest clear change, prove the behaviour and move on.

09

Improve the architecture behind boundaries

Once the application runs on a supported runtime, architectural work becomes easier to judge.

Look for boundaries around capabilities rather than files that happen to be large. Renewals, payments, documents and notifications are useful seams because each has recognisable inputs and outcomes.

A capability can be isolated behind a service or API while the old screens continue to use it. A new interface can replace one route at a time. Database access can move into a clearer layer without rebuilding the entire product. These changes reduce coupling while keeping the business journey available.

Moving to Laravel or another maintained framework may be sensible when its conventions, security support and ecosystem solve real ownership problems. It is not mandatory, and the framework name is not proof that the application has become maintainable.

A framework migration should have a specific benefit: clearer routing, consistent validation, safer authentication, supported dependencies, easier testing or a team that can realistically own it. Otherwise it risks becoming a long translation exercise with little visible value.

10

Use containers after you understand the environment

Containers can turn the runtime into a repeatable definition. They are useful when the team knows which PHP version, extensions, system packages and web server settings the application needs.

Used too early, a container can package confusion. An undocumented command copied from the old server into an image is still undocumented behaviour, only in a newer format.

The same applies to a cloud move. New hosting can improve support, deployment and resilience, but it also changes networking, storage, certificates, monitoring and operational ownership. It should be a deliberate stage with its own checks, not background noise during the PHP upgrade.

By this point, the earlier inventory earns its keep. The team can build the environment from known requirements, compare it with the baseline and explain why each component exists.

11

Release with a rollback route

The final test is not whether the new application works on a developer's machine. It is whether the business can move to it safely.

Plan the production release around the protected journey. Decide how data changes will be applied, how long the old and new environments can coexist and which signals will stop the rollout. Backups must be recent, restorable and appropriate for the data being changed.

Database migrations deserve particular care. A code rollback is not enough if the new release has removed or transformed data in a way the old code cannot read. Prefer backward compatible stages where the old and new application versions can operate during the transition. Destructive cleanup can wait until the new path has proved stable.

Monitor error rates, queue failures, response times and the business outcomes that matter, such as completed renewals and successful confirmations. A release can be technically healthy while silently skipping a step customers rely on.

Write down the rollback decision before the release begins. Under pressure, a clear threshold is more useful than a hopeful conversation about whether to wait another ten minutes.

12

Stop when change becomes ordinary

Not every old line of PHP needs replacing.

The valuable outcome is an application running on a supported platform with reproducible environments, known dependencies, protected business journeys, visible failures and a release process the team can repeat.

At that point, improvements can be chosen for business reasons. The next payment change does not require a rescue project. A new developer can build the application without copying a mystery server. The team can decide whether a framework migration, interface redesign or service split is worth funding with much better evidence.

Sometimes that evidence will support replacement. The application may no longer fit the operation, the data model may prevent essential work or the cost of keeping old behaviour may exceed the value it provides. Discovery is not wasted in that case. It identifies what the replacement must preserve and makes the transition safer.

Modernisation is not a single dramatic launch. It is the point at which the business stops depending on unknowns and starts making controlled changes again.