Agents can read a page index at https://migrateforge.com/llms.txt, or request any page with Accept: text/markdown.

Blog

How we verify a PHP to Java migration: responses, DB writes and outgoing calls

A PHP-to-Java cutover is only as good as the comparison you run before it. I record real traffic, replay it in a pinned sandbox, and compare HTTP responses, database writes and outgoing API calls.

TL;DR. A PHP-to-Java cutover is only as good as the comparison you run before it. I record real traffic against the PHP application — HTTP responses, every database change, and every outgoing API call — then replay those journeys against the Java version in a sandbox with the clock, timezone, sql_mode and charset pinned. I compare all three channels, because a matching response can still hide a destructive write. Before any Java number means anything, the PHP application has to reproduce its own recording, at 99.5% or better. And the checker itself has to be tested: a harness that never contradicts you is not a harness.

I spend a lot of time on PHP-to-Java migrations thinking about a question that looks simple: how do you know the new system behaves like the old one?

The usual answers are a test suite, a QA pass, and a staging week where people click around. Those are useful. They are also incomplete. Legacy PHP applications accumulate behaviour that nobody wrote down: a side-effecting delete, a rounding rule, a call to another system that only happens on one path. If you only compare the HTTP response, you will miss the part that actually costs money.

So I do three things. I record real user journeys against the PHP application. I replay them against the Java 21 / Spring Boot version in a deterministic sandbox. And I compare the HTTP response, every database write, and every outgoing API call. Cutover stays blocked until they match.

This is the method, including the parts that failed.

HTTP agreement is not behavioural agreement

The example I keep coming back to is a delete.

I migrated a delete endpoint. The Java version returned the same HTTP status as the PHP version and followed the same redirect. On the response alone, the two systems agreed. The database write did not. The migrated delete also removed the client’s invoices and payments.

That is the kind of bug a browser test can walk past, because the page looks fine. It is also the kind of bug that would have shown up in production as missing financial records. The only reason it was caught before cutover is that the comparison included database writes, not just the response.

The same process has also caught a missing login check, data visible across tenants, and a skipped cashback payout. Some of what it found was not introduced by the migration at all: it was already wrong in the original PHP. That is useful too. If you are going to move a system, you should know which defects you are carrying with you.

Record real traffic, not the paths you remembered to test

I do not start with invented test cases. I record real traffic against the PHP application: the HTTP responses, every database change, and every outgoing API call.

Recorded journeys have a bias of their own, which I will come back to. But they have a property that a handwritten suite often lacks. They include the awkward paths people actually take: the retries, the empty submits, the deletes, the odd query parameters. Those are the places where PHP and Java tend to drift.

The recording is the fixture. Everything after it — replay, comparison, the decision to allow cutover — is only as strong as what was captured.

Replay in a sandbox that does not invent differences

A comparison is only useful if a mismatch means a real behavioural difference, not an environmental one.

I replay the same journeys against the Java version in a sandbox where the clock, the timezone, sql_mode and the charset are pinned. If the PHP ran in a particular timezone or wrote datetimes a particular way, the Java side has to do the same, or the diff fills up with noise. The same is true of MySQL sql_mode and charset. A string that was legal on one side and truncated on the other is a real difference. A timestamp that is “wrong” because the clock moved is not.

The point of pinning the environment is not to make the systems look the same. It is to make sure that when they look different, the difference is in the application.

Compare all three channels

Each channel catches something the others miss.

Responses tell you about status codes, redirects, headers and body content. They miss silent writes. A 200 and a clean redirect can sit on top of a delete that went too far, or an update that never happened.

Database writes tell you about inserts, updates and deletes, including the ones that were not supposed to happen. They miss calls that never touch your database: a request to another service, a webhook, a payment or notification call.

Outgoing API calls tell you about those outward effects. A matching page that sent a different payload, or failed to send one, is still a failed migration. The other system will notice even if your UI does not.

The delete I mentioned earlier is the simplest illustration: identical HTTP response, identical redirect, and a write that would have removed invoices and payments. If we had only compared the response, we would have shipped it.

The PHP application has to match itself first

Before any Java number means anything, the PHP application has to match itself. I replay the recorded journeys against the same PHP system that produced them. I want that self-comparison at 99.5% or better. If the original system cannot reproduce its own recording, you are not measuring a migration. You are measuring a flaky harness.

I learned this the slow way. I once spent two days chasing differences that looked like migration bugs. They were leftover probe rows that only one side could see. The Java was not wrong. The fixtures were dirty. Until the PHP side could replay cleanly against its own recording, every Java mismatch was a waste of time.

This step is unglamorous, and I would not skip it again. It is also the step that makes the later numbers honest. A recorded match against a recording the PHP application itself cannot reproduce is not a result. It is a measurement error.

Then test the checker

A harness that never contradicts you is not a harness. I plant deliberate bugs in the Java and measure how many the checker actually catches.

The self-test catch rates so far are 57.14% on WA Blast Pro wave 1, and 35.89% on InvoicePlane wave 1. Those are not comfortable numbers, and I publish them next to the parity figures for that reason. 100% parity means every recorded fixture matched. It does not mean the checker would catch every possible bug.

The pattern in what it catches, and what it misses, has been consistent. Lost writes and missing escaping are always caught. NULLs and .00 amounts are missed, because the recordings never produce them. That is a coverage problem, not a comparison problem. If a journey never writes a NULL, the checker has no opportunity to notice that the Java side would handle a NULL differently. The same is true of a .00 amount that never appears in real traffic. The planted-bug tests showed that gap clearly. Closing it means changing what gets recorded, or adding cases the live traffic does not provide, not pretending the three-way comparison is complete.

I would rather have a checker with a published miss rate than one that only ever agrees with me.

What the benchmarks actually show

The numbers below are from two benchmarks, not from paid client work. I want to be clear about that. This is early. These results are from systems we already had in hand.

  • WA Blast Pro, my own production multi-tenant WhatsApp SaaS, written in plain PHP.
  • InvoicePlane, a public open-source invoicing application on CodeIgniter 3, written by other people.

Together that is 858 fixtures, at 100% parity, after hand fixes. First-pass parity, before those fixes, was 82% on one wave, with 9.7 hand fixes per 1,000 PHP lines. The generator is not the judge. Replay closes the gap, and engineers still fix things. The gate tells them where.

The bugs I listed earlier — the over-broad delete, the missing login check, the cross-tenant data, the skipped cashback payout, and defects already in the original PHP — came out of this process. Some of them would have been serious in production. Catching them on a benchmark is not the same as catching them on a client’s system, but it is why I trust the three-way comparison more than a green HTTP diff.

What this covers today

The method is in use today for plain PHP and CodeIgniter 3. Laravel is next, as a source. I am not going to pretend the Laravel path is ready.

I also will not pretend that recorded-journey comparison is a complete substitute for a thoughtful review of the Java. Parity tells you the new system behaves like the old one on the journeys you recorded. It does not tell you whether the Java is well structured, whether the transaction boundaries are right, or whether it will hold up at a volume the recordings never reached. Those are separate questions, and they still need an engineer.

The honest sequence, as I now run it, is narrow. Make the PHP application match its own recording. Replay the same journeys against Java in a pinned sandbox. Compare responses, database writes and outgoing calls. Test the checker with planted bugs, and treat the miss rate as part of the result. Keep cutover blocked until the recorded journeys match. Then, separately, read the Java.

Start with a free migration report.

Or email us to book a call if you would rather talk through the PHP application first.