A PHP app stores order statuses as a string-backed enum in the database; what breaks when you rename a case, change a value or add a case?

## Two identities per case A backed case has two identifiers, and they live in different places: - The **case name** (`OrderStatus::OutForDelivery`, `->name`) lives in **code**. - The **backing value** (`'out_for_delivery'`, `->value`) lives in **data**: database rows, cache entries, queue messages, JSON sent to apps and partners. The rule that keeps evolution manageable: **persist `->value`, never `->name`**. Then the name is free to change with a refactoring, and the value becomes the stable contract. ## Renaming a case Changing `case Placed = 'placed'` to `case Received = 'placed'`: 1. Stored rows are unaffected; `from('placed')` now returns `Received`. 2. Every remaining `OrderStatus::Placed` in code fails with `Error: Undefined constant OrderStatus::Placed` **when that line runs**, not when the file compiles. Static analysis or a full test run catches them; a rarely used branch may not be hit for weeks otherwise. 3. Anything that stored the **name** breaks: PHP's native `serialize()` records enum cases by name, so cached or queued serialized objects fail to unserialize, as does any column or log that stored `->name`. ## Changing a backing value Changing `'out_for_delivery'` to `'dispatched'` is a **data migration**, not a refactoring: - Existing rows still contain `'out_for_delivery'`. Loading them with `from()` throws `ValueError: "out_for_delivery" is not a valid backing value for enum OrderStatus`. - Loading them with `tryFrom()` returns `null`. If the code then falls back to a default (`?? OrderStatus::Placed`), orders silently jump back to an earlier state, and the next save writes the wrong value: **silent data corruption**. - Messages already in a queue and mobile apps still sending the old value keep arriving after the deploy. A safe sequence: | Step | Change | |---|---| | 1 | Accept both values on input: a static `fromStored(string $v)` maps the old value to the case | | 2 | Migrate stored rows to the new value | | 3 | Switch writes to the new value (the case's `value`) | | 4 | Remove the legacy mapping once old messages and clients are gone | Often the cheapest answer is simply not to change values once they have shipped. ## Adding a case Adding `case Refunded = 'refunded'` is the most common change and the safest for storage, but it touches behaviour: - Every `match ($status)` **without** a `default` arm throws `UnhandledMatchError` when a refunded order reaches it. That is the desired outcome, because it forces each decision point to handle the new state, but only if tests or a static analyser find those `match` expressions before production does. - Methods on the enum (`label()`, `canTransitionTo()`) must include the new case. - A database column restricted to the known values (a check constraint or a native enum column type) must be widened in a migration **before** the code writes the new value. - Consumers that validate values against a list, such as a mobile app, need to tolerate an unknown status. ## Loading discipline - Data your system wrote: `from()`, so drift is an exception at the read, close to the cause. - Data from outside: `tryFrom()` with an explicit error, and a type check first on int-backed enums, since a non-numeric string throws `TypeError` even from `tryFrom()`. - Never convert `null` from `tryFrom()` into a default state without logging it. ## Tests that make evolution safe A few cheap tests catch most enum-evolution mistakes before production: - iterate `OrderStatus::cases()` and assert that `label()` and every other per-case method return a value for each case, so a new case without an arm fails in the test suite rather than in production; - assert that `OrderStatus::from($case->value) === $case` for every case, which catches duplicate or mistyped values; - keep a fixture of the values that exist in production data and assert each still maps with `from()`, which turns an accidental value change into a failing test. ## Summary - Names are code; values are data. Store values. - Renames are refactorings plus a check for anything that stored names. - Value changes are migrations with a transition window. - New cases are safe for storage if `match` expressions and constraints are updated with them.