PHP Application Modernization

Starting point — a business-critical system nobody could safely change

The application ran on PHP 5.6 — a version without security support since December 2018. It processed customer data, billing and reporting every day, yet it had no tests, no backups and no documentation. Deployments were manual and happened over FTP, after hours; the full cycle from decision to production took about two weeks. Incidents were regular and diagnosed from memory, because nothing recorded how the system actually behaved. The team had stopped asking for changes — the backlog was full of features nobody dared to request. This is what technical debt looks like when it matures: not a number in a spreadsheet, but a business that quietly works around its own system. The compliance angle made it urgent: personal data processed by an interpreter with publicly documented, unpatched vulnerabilities is a GDPR exposure, not just a maintenance annoyance.

Why we did not rewrite from scratch — and what a legacy modernization strategy actually is

The instinct with legacy code is a full rewrite — and it is usually the most expensive way to fail. A rewrite means rebuilding years of undocumented business rules from scratch, with no way to verify the new system against the old one until it is too late. The alternative is a modernization strategy: keep the system running while improving it in verifiable steps. Audit first, then a test safety net, then incremental refactoring, then automation, then monitoring. Every step is independently safe and delivers value on its own. That is exactly how this project ran — and it is the approach behind every guide in our legacy modernization hub. Legacy code, by the way, is not “bad code”: it is working code written in the past, carrying business value that a rewrite would put at risk.

Step 1 — code audit: measuring the problem before touching anything

Modernization starts with discovery, not with code. We scanned the codebase with PHPCompatibility (constructs removed or changed in newer PHP versions), ran PHPStan for type and call errors that would become fatal on the target version, and inventoried every dependency with Composer — flagging abandoned libraries with no PHP 8-compatible release. In parallel we mapped the runtime environment: the exact PHP version and extensions, php.ini settings, the web server (nginx), the database (PostgreSQL) and Redis usage. This runtime discovery matters more than it sounds: configuration differences between environments are the most common source of “it works on staging, it broke in production”. The audit produced a blocker list split into three categories — auto-fixable, needs a human decision, library must be replaced — which doubled as the migration plan and the estimate. It also surfaced the documentation gap: critical knowledge existed only in the original developer’s head. We closed it with structured interviews and a written runtime map.

Step 2 — characterization tests: a safety net before the first refactoring

Refactoring code without tests is not modernization — it is gambling. But a legacy system has no tests to run, so the first testing task is different: characterization tests (the technique described by Michael Feathers) record what the system actually does today — including behaviour that looks like a bug — so any change that alters it becomes visible immediately. We covered the critical business paths first: login, customer processes, billing, document generation and reporting — 15–20 end-to-end tests caught the vast majority of risks. They ran in CI on the target PHP version from day one, which turned the upgrade from a leap of faith into a process with a clear acceptance criterion: green tests are the deployment condition. No test, no release — that rule alone eliminated the “we will hear it from users” release model.

Step 3 — module-by-module refactoring with Rector, not a big-bang rewrite

With a safety net in place, we refactored one module at a time: billing first (highest risk), then reporting, the admin panel and finally the integrations. Rector did the mechanical work — its rulesets for version transitions automated 80–90% of the changes from PHP 5.6 through 7.4 to 8.x: removed functions replaced, syntax modernized, deprecated constructs eliminated. Every Rector run went through the same loop: generate the diff, review it, run the full test suite, commit — version by version, so any error could be attributed to a specific change. Abandoned libraries were replaced with maintained alternatives; where none existed, the functionality moved into our code with tests first. Where a module needed deeper restructuring, we used the strangler fig pattern: new code grew behind the same interfaces while the old implementation kept serving traffic — the system was never “half-migrated”, it was always working. Symfony was evaluated as a framework target early on; the pragmatic choice was Laravel on PHP 8.4, matching the team’s skills and the existing database layer.

Step 4 — from FTP to CI/CD: GitHub Actions, Docker and reversible releases

The deployment process was the second root cause of incidents, so it got the same treatment as the code. We built a pipeline in GitHub Actions: every push runs the PHPUnit suite, static analysis and the build; merges to main deploy to staging automatically, and production releases are a monitored, one-command operation. Docker containers make staging and production genuinely identical — same PHP version, same extensions, same configuration — which eliminated the entire class of environment bugs. Every release has a rollback path: the previous image stays available, database migrations are written to be backward-compatible for one release, and the old PHP version remained on the server until stability was confirmed. Deployment time dropped from two weeks to two days, and — more importantly — releases stopped being events. Jenkins and Ansible were on the table; for a project of this size, GitHub Actions plus Docker was the pragmatic combination with the least moving parts to maintain.

Step 5 — monitoring: incidents should be alerts, not complaints

An application without monitoring is a system whose failures you learn about from customers. We instrumented the application with New Relic (response times, slow queries, error rates), added structured error tracking and log alerts, and put thresholds on the metrics that matter for the business: failed logins, payment-path errors, queue depth in Redis, database response times. Deprecation warnings from PHP 8 became a to-do list instead of noise — each one a small, scheduled cleanup rather than a future incident. The first month of alerts paid for the whole monitoring layer: two slow queries were found and fixed before users ever noticed them. Incident detection moved from hours (user reports) to minutes (alerts), and mean time to resolution dropped with it.

Challenges along the way — what no modernization plan shows

Every legacy modernization runs into challenges that no plan shows. First: abandoned libraries — several dependencies had no PHP 8 release and no maintained alternative, so their functionality had to be rebuilt in our own code, tests first. Second: undocumented business rules — behaviour that looked like a bug turned out to be a requirement; characterization tests froze it as a contract instead of “fixing” it silently. Third: key-person risk — knowledge about the system lived in one head, so we ran interviews and documentation in parallel with the refactoring. Fourth: resistance to change — after years of incidents the team feared every deployment; the first months of a green pipeline and alerts instead of customer phone calls turned that around. Fifth: environment drift — “it works on staging” stopped being an argument only when Docker made the environments identical. None of these challenges disappear with any methodology — the difference is that staged modernization makes them visible and solvable one at a time, instead of leaving them buried inside a big rewrite.

The PHP 5.6 → 8.4 migration itself — what broke and what we gained

The version path ran through checkpoints — 5.6 → 7.4 → 8.x — rather than one jump across three generations, so each step had its own test cycle and deployment. What actually broke was predictable in hindsight and expensive without preparation: removed functions (each(), create_function(), the old mysql_* extension, the /e modifier in preg_replace), stricter type handling that turned silent coercions into errors, null passed to non-nullable parameters (deprecated in 8.1), and dynamic properties (deprecated in 8.2) that several older libraries relied on. The characterization tests caught every one of these before production. The gains arrived with 8.x: JIT compilation, attributes instead of annotations, enums, constructor property promotion and readonly properties — and a measurable performance improvement of the interpreter itself, tens of percent on the heaviest endpoints, without touching business logic. PHP 8.4 is in full support until December 2028, with PHP 8.5 already available — the platform is now ahead of the roadmap instead of years behind it.

The team — removing the key-person risk and making modernization stick

Technology was half of this project; the other half was people. The original system depended on one developer who understood it — a key-person risk that had already caused one crisis when they were unavailable. We documented the runtime environment, wrote the deployment and rollback procedures down, and paired with the internal team throughout: developers and system administrators working through the same pipeline, closing the gap that DevOps culture is about. By the end, the client’s own developer shipped through the pipeline, read the alerts and planned the next module upgrades independently. Modernization that leaves the team behind is not finished — the handover was part of the acceptance criteria, not an afterthought.

Results — before and after, with numbers

Twelve months after the final module release: zero critical incidents, against a baseline of regular outages with emergency fixes. Deployment time down from 2 weeks to 2 days; deployment frequency up from “only when necessary” to several releases a month. Maintenance costs down 60% — the legacy premium for PHP 5.6 skills disappeared, and so did the manual release rituals. Backups run automatically with tested restores; monitoring detects anomalies in minutes. The test suite that started as 15–20 characterization tests now guards every critical path, and it is the reason dependency updates — previously impossible — are now a routine task. The metrics table above collects the before/after data from the anonymised project. The most important number is not in the table: the backlog the business had stopped requesting is moving again.

Business results — performance, scalability, reliability and user experience

Technical metrics translate into business language. Performance: JIT and OPcache in PHP 8.x plus fixing two slow queries made the heaviest screens tens of percent faster — without changing business logic. Scalability: Docker containers and Redis queues let the application scale horizontally when traffic grows, instead of replacing the server with a bigger one. Reliability: zero critical incidents in 12 months is not just about reputation — it means no more nights of emergency fixes and a predictable SLA for end customers. User experience: the modernization preserved full feature parity — users never saw the migration, but they started feeling a faster system; forms and reports respond noticeably quicker. Growth: an unblocked backlog means new features and new revenue instead of another year of status quo. Legacy modernization, then, is not a technical project — it is an investment in growth: maintenance costs down 60%, deployments from 2 weeks to 2 days, and a platform ready for the next years of development.

When modernization pays off — and how to start

The signals are consistent across legacy projects: an end-of-life PHP version, no tests, manual deployments, incidents diagnosed from memory, and knowledge concentrated in one person. Any two of those mean the cost of doing nothing is already compounding — maintaining a legacy system typically costs 2–3 times more than its modern equivalent, before counting the security and compliance exposure. Modernization pays off when the cost of doing nothing exceeds the cost of the work; for systems like the one in this case study, that point is usually years in the past. The first step is always the same and always cheap relative to the problem: a code audit that produces a blocker list, a risk map and a staged plan with an estimate. Typical scopes: a small project (a dozen thousand lines) modernizes in days to weeks; a medium system with frameworks and integrations takes 2–8 weeks; large legacy systems without tests are done in stages over several months. If you recognize your system in this case study, start with the audit — everything else is a decision you make with data in hand.

Lessons learned

Three lessons from this project, in order of importance. First: tests before refactoring, always — characterization tests are the difference between modernization and gambling, and they are the cheapest insurance in the whole program. Second: module-by-module beats big-bang — every module shipped and stabilized on its own, the system never stopped working, and the business saw progress from the first month instead of waiting a year for a rewrite. Third: monitoring from day one — the observability layer paid for itself in the first month, and it is what makes the other two lessons verifiable in production rather than on a whiteboard.

Frequently asked questions