Compatibility on Brian Faust

A Rewrite Can Change Data Without Changing the Price

Thu, 01 Oct 2026 00:00:00 +0000

The Go history append preserved the existing JSON. That looked reasonable: read a stored transition list, add the new transition, leave everything else alone. Unfortunately, leaving everything else alone wasn’t what the PHP implementation did.

The shared idempotency updater in my rating engine read history through an Eloquent array cast, appended a transition, and assigned the resulting value back to the model. That round trip could turn an old nested {} into []. The Go translation preserved {} instead. Both could complete the operation and return the same price while storing different histories.

Stored Data Is a Caller You Cannot Find with Code Search

Sun, 01 Dec 2019 00:00:00 +0000

An enum migration looked mechanical. A package-backed value object became a native PHP backed enum. The domain concept stayed the same, the new cases were easy to search, and current code wrote the canonical values. It was exactly the kind of refactor that looks finished after a clean source search.

Then an older row loaded a lowercase value. The native enum expected the same word with different casing and rejected it during hydration.

Deprecation Is a Migration, Not a Warning

Tue, 01 Oct 2019 00:00:00 +0000

A billing rewrite introduced durable export records before removing several legacy queue jobs. Each new worker carried a record identifier. The export type, payload snapshot, attempts, failure details, and retry state lived in the database. A registry selected the current handler.

That order matters. A queued object is not merely code waiting to run. Its serialized class name and properties are data, even if nobody thinks of them as a schema. Delete the class while an old payload remains, and PHP can deserialize it as an incomplete object which no longer has the method the worker expects.

Renaming a Field Is a Protocol Migration

Thu, 01 Nov 2018 00:00:00 +0000

An API changes serviceIds to deliveryOptionIds. The new name describes the domain better, and the implementation is easier to read. It is probably the better name. That is also beside the point.

An existing client still sends:

{
 "serviceIds": ["express"]
}

The request now fails validation before any application code runs. Nothing about the client’s intent changed. The server chose a cleaner name and turned that preference into a breaking protocol change.

Data Outlives the Code That Created It

Fri, 01 Dec 2017 00:00:00 +0000

A failed queue record kept returning. Its payload named a mail class the running application could not resolve correctly, so retrying it could only repeat the same failure.

The workaround was blunt: once a minute, delete failed records whose payload matched that job. It stopped an unusable delivery attempt from disturbing the queue, but it obviously did not make the payload readable.

That small incident exposes an awkward storage contract. Serializing an executable object does not merely store its arguments. It preserves facts about the code which created it: class name, namespace, property layout, and sometimes framework behavior. The payload can live much longer than those facts.