Modernising a PHP monolith with the strangler-fig pattern
Large rewrites fail often enough that most engineers have a story about one. The strangler-fig approach replaces a legacy system piece by piece while it keeps running, so that value arrives early and risk stays small. Applied to an ageing PHP monolith, it starts with tests and a routing facade, not with a new framework.
Why not rewrite?
A full rewrite has to rediscover every rule the old system implements – including undocumented ones that customers rely on – while the old system keeps changing. Value arrives only at the end, and the end tends to move. The strangler-fig pattern, described by Martin Fowler, takes the opposite approach: build new functionality at the edges of the old system, route traffic to it gradually, and remove old code only once the new path has proven itself in production.
The approach suits PHP monoliths particularly well, because they are typically request-oriented: each URL maps to a script or controller, so routing individual endpoints elsewhere is natural.
Step 1: understand and characterise
Start by measuring. Which routes receive traffic, which change most often, which cause most incidents, and which hold the most business value? Access logs, error logs and version-control history answer these questions quickly. Map the modules and their database tables; legacy monoliths often share tables across features in ways that the code structure does not reveal.
Then write characterisation tests – a term from Michael Feathers’ Working Effectively with Legacy Code – for the routes you plan to touch first. These tests record what the system does today, not what it should do: given this request and this database state, this is the response. Quirks are captured deliberately; whether to keep them is a later business decision. Recording real traffic in a test environment and replaying it is an efficient way to build a broad suite.
Step 2: put a facade in front
All traffic must pass through a point where you can decide, per route, whether the old or the new implementation answers. Often the existing web server or reverse proxy can play this role; an API gateway works too. Initially the facade sends everything to the monolith. As capabilities are extracted, individual routes – or a percentage of traffic for a route, or specific customers – are switched to the new service.
The facade is also where you add what the monolith lacks: consistent authentication, rate limiting, request IDs and metrics. That alone often improves operations before any code is migrated.
Step 3: choose what to extract first
Good first candidates combine meaningful value with limited coupling: a capability that changes often, causes pain, and owns most of its own data. Read-heavy features are easier than ones that write to many shared tables. Avoid starting with the core of the domain – the order engine, the ledger – until the team has practised the mechanics on something less critical.
For each candidate, decide where it goes. Sometimes that is a separate service; often it is a cleanly structured module in a modern PHP application, sharing infrastructure with the monolith but not its code. Modernisation is about boundaries, tests and deployability, not necessarily about changing language.
Step 4: run in parallel and compare
Before switching a route, run the new implementation in shadow mode: the facade sends a copy of each request to both, returns the monolith’s answer, and logs differences. Comparison reveals missing rules and edge cases with real traffic and no customer impact. When the difference rate is acceptably low and understood, switch a small share of live traffic, watch error rates and latency, and increase step by step. Keep the switch reversible until the old code is deleted.
Shadowing only works safely for reads or for writes that the new implementation performs against an isolated copy; never let both implementations write to the same production data.
Step 5: move the data
Data is where strangler migrations become difficult. While both implementations exist, one of them must own each piece of data. Common strategies are:
- Shared database, new owner: the new service takes over writes to specific tables; the monolith reads them or calls the service. Simple, but couples schemas.
- Synchronisation: the new service has its own store, and changes flow between stores via events or change data capture during the transition.
- Bulk migration with cut-over: for well-bounded data, copy, verify and switch ownership in one controlled step.
Whatever the strategy, define ownership explicitly and remove dual writes as soon as possible – they are a common source of subtle inconsistency.
Step 6: delete the old code
A migration is not finished until the legacy path is removed. Once a route has served all traffic from the new implementation for an agreed period without issues, delete the old code, tables and configuration. Teams that skip this step end up maintaining two systems indefinitely, which is worse than the starting point. Track “legacy code removed” as a visible metric alongside “features migrated”.
Keeping the organisation aligned
Strangler migrations run for months, sometimes years, and compete with feature work. They succeed when the organisation treats them as a product with visible progress rather than as background refactoring. A simple migration board – capabilities, their state (legacy, shadow, partial, migrated, legacy deleted) and their owners – keeps everyone oriented.
New features should be built on the new side by default. Every feature added to the monolith during the migration is another thing to migrate later. Where that is impossible, document it explicitly as migration debt.
Finally, keep the old system healthy while it lives. Security patches, PHP runtime upgrades and monitoring for the monolith remain necessary until the last route is gone; neglecting them in anticipation of retirement is a common source of incidents.
Worked example: Extracting invoicing from a monolith
A twelve-year-old PHP application handled customers, orders, invoicing and reporting. Invoicing changed most often and caused most incidents. The team recorded a week of invoicing traffic in staging and turned it into 600 characterisation tests, then placed NGINX routing rules in front of the monolith. A new PHP 8 invoicing module with its own tables received the invoicing routes in shadow mode for two weeks; comparisons revealed rounding rules for one customer group that nobody had documented. After fixing them, traffic moved over in 10%, 50% and 100% steps. Order data stayed with the monolith and was read through an internal API. Three months later, 9,000 lines of legacy invoicing code and four tables were deleted.
Common pitfalls
- Starting with the most coupled core of the domain.
- Changing behaviour and architecture in the same step.
- Shadow-testing writes against shared production data.
- Long-lived dual writes between old and new stores.
- Never deleting the legacy path after migration.
Questions & answers
Do we have to leave PHP?
No. Modern PHP with strict types, static analysis and a clean architecture is a sound platform. Choose the target technology for the team and the problem, not as a reaction to the old code.
How long does a strangler migration take?
It depends on size and coupling, but value arrives with the first extracted capability, often within weeks. The full migration is a sequence of small projects rather than one large one.
What if the monolith has no tests at all?
That is the usual starting point. Begin with characterisation tests at the HTTP level for the routes you touch; you do not need full coverage before starting, only coverage of what you change.
Checklist
- Measure traffic, change frequency and incidents per route.
- Write characterisation tests for the first candidates.
- Introduce a routing facade with metrics and request IDs.
- Pick a valuable, loosely coupled first capability.
- Shadow, compare and switch traffic gradually.
- Define data ownership and end dual writes quickly.
- Delete legacy code and track its removal.
Primary sources
- Fowler, M., “StranglerFigApplication”, martinfowler.com, 2004
- Feathers, M., Working Effectively with Legacy Code, Prentice Hall, 2004
- Newman, S., Monolith to Microservices, O’Reilly, 2019
- PHP documentation – PHP 8 language reference and migration guides