Replacing a legacy PHP application does not require rewriting it all at once. A gradual replacement lets you move capabilities while the business continues to operate, but it only works if you precisely decide which system handles each operation and which one governs each piece of data. Without those boundaries, both applications can end up executing different rules, accepting incompatible writes, and producing results that are difficult to reconcile.
The goal is not to maintain two implementations in parallel indefinitely. It is to move responsibilities in a controlled way, verify that the new solution preserves the required behavior, and retire old dependencies when sufficient evidence is available. This requires functional boundaries, observability, one source of truth for each data domain, and progress criteria agreed on by engineering and product.
Why having two applications in parallel is not enough
Having an old application and a new one available does not define a migration. If both accept the same operation, they may apply different rules for validations, permissions, prices, states, or side effects. The problem often surfaces late: an invoice is calculated in two different ways, a notification is sent twice, or a status change is not reflected in every system.
A gradual replacement of a legacy PHP system needs to explicitly describe which capability is being moved, which system receives requests, and where authority over the data resides. The boundary must be functional, not simply a list of controllers or tables. A capability such as “manage a return” may involve authorization, inventory updates, and a refund; splitting it without understanding those dependencies creates a misleading boundary.
Before changing the routing, document the observable behavior: inputs, outputs, relevant errors, permissions, side effects, and external dependencies. Distinguish business rules from incidental implementation details. Not all historical behavior needs to be preserved, but any intentional change must be approved and tested as such, rather than silently attributed to the migration.
Choose a first capability that can be verified
The first candidate does not have to be the smallest or most visible one. Prioritize a capability with understandable boundaries, reasonable coupling, and a verifiable outcome. Operational value matters too: a migration can reduce risk, unblock frequent changes, or improve an area that the business needs to evolve.
- Coupling: Identify calls to other modules, direct access to shared tables, scheduled tasks, and dependencies on global state. Many connections do not prevent a migration, but they increase the cost of defining the boundary.
- Verifiability: Check whether you can define representative cases and observe the result without relying on subjective interpretation.
- Impact and reversibility: Assess what happens if the capability fails and whether it can return to the previous route without losing data or repeating external effects.
- Operational readiness: Confirm that there are owners, metrics, and procedures for investigating discrepancies before exposing real traffic.
A brief inventory helps: capability, consumers, data it reads and modifies, external effects, product owner, and technical owner. If you cannot determine who uses an operation or which system updates a piece of data, first improve your understanding of the system; migrating it immediately will not reduce uncertainty.
Define routing and data authority
The router must explicitly decide which implementation handles a request. Depending on the architecture, this could be an application layer, a gateway, or a decision at the entry point. What matters is that the criterion is observable and consistent: by capability, customer, operation, or controlled cohort. Avoid allowing two routes to process the same order without coordination.
At each boundary, assign one owner per data item or aggregate. If the new system owns orders, for example, the old one should no longer modify them directly through shared table access. Other components can query a defined interface or receive changes through events, depending on consistency requirements. Sharing a database can be a transitional stage, but it is not the same as sharing authority.
Synchronization must state its direction and purpose. A read copy can feed reports or legacy consumers; it must not accidentally become a second authorized write path. If events are exchanged, define identifiers, ordering where necessary, retries, deduplication, and handling of failed messages. Also clarify how delays are detected and who resolves divergences.
Avoid ambiguous dual writes
Writing to two systems during a request may seem like a simple way to keep them aligned, but it introduces partial failures: one write can complete while the other does not. Retrying the request could duplicate an operation. Without a strategy for idempotency, reconciliation, and errors, there is no single transaction to guarantee consistency between independent applications.
Prioritize a single write authority for each operation. During a transition, the owning system can publish changes to update a projection or compatibility copy. For asynchronous processes, reliably record the change and its message within the same transactional boundary when the infrastructure allows it, and design idempotent consumers. If a specific constraint requires dual writes, treat them as a temporary exception: specify the order, possible failures, reconciliation, and the date or condition for removing them.
Historical data copies also require rules. Define how the initial state is loaded, how concurrent changes are applied, and how the result is verified before changing ownership. Do not assume that a successful import means relationships, derived states, and permissions are complete.
Compare behavior without duplicating effects
Comparison reduces risk when it distinguishes computation from execution. One technique is to send a copy of the input to the new implementation in observation mode and compare its response with that of the active system, without allowing the copy to send emails, charge payments, change inventory, or trigger other external effects. That execution should use controlled data and dependencies, or replace effects with adapters that only log the intent.
Compare results semantically: states, amounts, decisions, and relevant errors, not necessarily the order of fields or timestamps. Use representative cases that include edge cases, incomplete data, permissions, and dependency failures. Add automated tests for critical rules, and retain anonymized or synthetic examples when real data is not appropriate for evaluation.
Shadow execution does not, by itself, prove that the new system can operate. It may not reproduce latency, concurrency, or real integrations, and a difference may reveal either a defect or an undocumented legacy rule. Every discrepancy needs a classification, an owner, and a resolution: fix it, accept an approved change, or exclude the case for a verifiable reason.
Instrument progress and prepare to roll back
Record the selected route, implementation version, correlation ID, and outcome of each operation. Measure errors, latency, retries, synchronization delays, and discrepancies, segmented by capability. Avoid logging secrets or unnecessary personal data; define access controls and retention periods for logs.
Before increasing exposure, agree on stop thresholds and who can halt progress. Rolling back does not always mean changing the routing: if the new system has already accepted writes, returning to the old application may leave it without the latest state. The procedure must specify what to do with in-flight operations, pending messages, and written data; rehearse it in an appropriate environment. Reversibility depends on state and effects, not just a configuration option.
Retire the old system under verifiable conditions
Retirement should be based on evidence, not on an isolated date. For a capability, confirm that all intended routes reach the new owner; that critical operations and their error cases are covered; that consumers and scheduled jobs no longer depend on the old component; and that no direct writes or reconciliation processes without an owner remain.
Then observe operations for a period agreed on with product and operations, taking into account load and the cycles relevant to that capability. Verify pending data, compatibility copies, and audit or retention requirements before removing components. Update documentation, alerts, and support procedures. Keeping an old component “just in case” also has a cost: it can retain permissions, vulnerabilities, and write paths that obscure ownership.
A practical sequence is: define the capability boundary, assign data authority, document behavior, prepare tests and observability, load or synchronize data, compare without side effects, route a controlled exposure, review results, and retire dependencies with explicit approval. If a stage has no acceptance criteria or owner, the migration is not yet ready to proceed.
