To modernize legacy PHP application code safely, work in four stages rather than one big rewrite: audit what you have, stabilise it with backups and basic tests, upgrade PHP and dependencies in controlled steps, then refactor only the riskiest parts. Each stage leaves the system working and releasable.
Signs you need to modernize legacy PHP application code
Age alone is not the problem. A ten-year-old application that is understood, tested and patched can be healthier than a two-year-old one nobody dares touch. These are the signals that matter:
- It runs on a PHP version that no longer receives security fixes. Check the supported-versions page on php.net for the current status of the version you use.
- Only one person understands how it works, and they are about to leave or already have.
- Deployments are manual, scary and done by copying files over FTP.
- Small changes break unrelated pages, because logic is duplicated or tangled together.
- Dependencies are vendored by hand, with no record of versions, or a package manager is missing entirely.
- Your hosting provider is pushing you to upgrade, and you cannot say what would break.
- New features take far longer than they should, and the team has stopped suggesting them.
If several of these are true, the risk is not abstract: security holes, outages and staff dependency all grow while you wait.
Step 1: an honest audit
Before changing anything, find out what you actually have. A useful audit answers questions rather than producing a thick report:
- Inventory. Which PHP version, framework (if any), database, extensions, cron jobs, third-party services and servers are involved?
- Dependencies. Which libraries are in use, which versions, and which are abandoned?
- Business criticality. Which features make money or hold the business together, and which are rarely used?
- Code health. Where are the largest, most tangled files? Where do bugs cluster? Static analysis tools can point to deprecated functions and type problems quickly.
- Security. Are there obvious problems such as unescaped output, string-built SQL queries, weak password storage or exposed admin tools? The OWASP-based PHP security checklist is a good yardstick.
- Operations. Who has server access, where are backups, and has a restore ever been tested?
End the audit with a short ranked list: what must be fixed now, what should be fixed soon, and what can wait. That list becomes your plan.
Step 2: stabilise before you change
Stabilising means making change safe. It is unglamorous work and it is what separates modernisation from gambling.
- Put the code in version control if it is not already, and agree on a branching and release process.
- Create a staging environment that mirrors production as closely as you can, with a copy of data that has been anonymised where necessary.
- Back up and test the restore. A backup you have never restored is a hope, not a backup.
- Add monitoring for errors and uptime, so you learn about failures before customers do.
- Record how deployment works and make it repeatable, even if the first version is just a documented script.
If the application has no automated tests, do not try to write them for everything. Start with characterisation tests around the most critical flows, such as login, checkout or invoice generation. These record what the system does today, so you can tell when a change alters it. For flows that are hard to cover in code, a written manual test script that someone executes before each release is a legitimate starting point.
Step 3: upgrade PHP and dependencies
Now you can upgrade with a safety net. The key principle is small, reversible steps.
- Fix deprecation warnings first, on the PHP version you currently run. Turn error reporting up on staging and read the logs.
- Upgrade dependencies that block the new PHP version, one at a time, running your tests after each.
- Move up one major PHP version at a time rather than leaping across several, and read the official migration guide for each version on php.net. Removed functions, changed behaviour and stricter type handling are the usual causes of breakage.
- Run the application on staging with the new version, exercise the critical flows, then release to production with a rollback plan.
- Introduce a package manager and a lock file if the project lacks them, so that dependency versions are recorded.
If you are moving between specific versions, the PHP 7 to PHP 8 upgrade checklist goes through the details, and if your project is built on Laravel, the Laravel upgrade guide covers framework-specific steps.
Step 4: refactor the riskiest parts of a legacy PHP application
Once the system runs on a supported version and you can release safely, improve the parts that cause the most pain. Choose by risk and change frequency, not by what looks ugliest. A messy file nobody edits can stay messy.
Good candidates are code that handles money or personal data, files that change in nearly every release, and areas with repeated bugs. Typical moves include:
- Extracting duplicated logic into functions or classes with clear names.
- Replacing hand-built SQL with parameterised queries or a query layer.
- Separating business rules from page templates, so rules can be tested.
- Wrapping an outdated library behind a small interface, so replacing it later touches one place.
- Introducing a framework gradually, route by route, when the application is large enough to benefit.
Add tests around each area before you refactor it, and keep each change small enough to review.
When a rewrite really is the better answer
A rewrite is sometimes right, but less often than people hope. It tends to be justified when the business model has changed so much that the old design no longer fits, when the technology cannot be run securely at all, or when the code is so tangled that even characterisation tests cannot be written. Even then, replacing it piece by piece, with the new and old running side by side, is usually safer than a big-bang switch. The trade-offs are discussed further in the article on refactor, rewrite or live with it.
Warning signs of a rewrite proposal that needs scrutiny: no list of what the old system actually does, a plan to freeze features for a long period, and an estimate that ignores the hidden business rules embedded in the old code.
What to document along the way
Documentation is the quiet payoff of modernisation. At minimum, capture:
- A one-page architecture overview: components, databases, external services.
- How to set up a local environment and how to deploy.
- A list of scheduled jobs and what each one does.
- Business rules you discovered that are not obvious from the interface.
- Decisions made and why, so the next team does not reverse them by accident.
Putting it together
Treat modernisation as a sequence of safe improvements: understand, stabilise, upgrade, refactor. Each step reduces risk and gives you something you can ship. If you want an outside view on your own system, the software development in Israel page explains how to start a conversation, or see the upgrade story for an Australian SME to compare how similar situations are approached in other settings.
Frequently asked questions
Is it safe to upgrade from PHP 5/7 straight to 8?
Jumping several versions at once increases risk, because each release removes or changes behaviour. The safer route is one major version at a time, fixing deprecation warnings and testing on staging at each step. Read the official migration guides on php.net, and check that your dependencies support the target version.
How do I test an application that has no tests?
Start with characterisation tests around the flows that matter most, such as login, checkout and invoicing, so you capture current behaviour before changing it. Add a written manual test script for hard-to-automate areas. Then add a test whenever you fix a bug or refactor a piece of code.
Rewrite or refactor?
Refactor in most cases. Incremental improvement keeps the system working and releasable while you reduce risk. Consider a rewrite when the design no longer fits the business or the technology cannot be secured, and even then replace it piece by piece rather than in one big switch.