Development
How to Use PHP Enums for Statuses and Options

Use PHP enums when a value must come from a finite, named set. A backed enum adds a stable string or integer representation for storage and APIs, while preserving a distinct PHP type inside the application.
Enums are a good fit for controlled order statuses. They are usually a poor fit for values administrators can create freely at runtime.
Use PHP enums for an explicit status set
Enums require PHP 8.1 or newer. This self-contained example defines three stored values and safely parses an external status:
<?php
declare(strict_types=1);
enum OrderStatus: string
{
case Pending = 'pending';
case Paid = 'paid';
case Cancelled = 'cancelled';
/** Returns the label displayed to a reader. */
public function label(): string
{
return match ($this) {
self::Pending => 'Awaiting payment',
self::Paid => 'Paid',
self::Cancelled => 'Cancelled',
};
}
}
/** Parses a supported string status at an external boundary. */
function parseOrderStatus(mixed $value): OrderStatus
{
if (!is_string($value)) {
throw new InvalidArgumentException('Status must be a string.');
}
return OrderStatus::tryFrom($value)
?? throw new InvalidArgumentException('Unsupported status.');
}
$status = parseOrderStatus('paid');
echo $status->value . ': ' . $status->label() . PHP_EOL;
The expected output is paid: Paid. Passing unknown or an array should throw the documented validation exception.
The PHP backed enums reference explains value, from(), and tryFrom(). The enum methods documentation covers adding behavior such as a label.
Choose between from and tryFrom deliberately
Use from() when the application expects a valid backing value and an unknown value represents an exceptional condition. It throws a ValueError for an unsupported scalar value.
Use tryFrom() when absence is part of normal input handling. It returns null for an unknown backing value. Validate the external input's type first so an array or object does not unexpectedly reach the enum conversion call.
Do not silently map an unsupported status to Pending. That can disguise corrupted data or a caller using a newer contract. Return a validation error or trigger a reconciliation path according to the boundary.
Persist the backing value intentionally
For a database row, store $status->value in the intended scalar column. Hydrate the enum at the repository boundary and decide what happens if an old row contains a value outside the current set.
Do not store a translated display label as the durable identifier. A label can change with language or copy editing; the backing value is part of the data contract.
When renaming an enum case in PHP, distinguish the case name from its backing value. Changing the backing value can require a data migration and coordination with external consumers, even if the new name seems clearer.
An enum does not implement the state machine
The enum says which statuses exist. It does not decide whether a cancelled order can become paid, who may perform that action, or whether a webhook is stale.
Keep transition rules in the component that owns order behavior. A payment confirmation might require a provider identity, an amount check, and an idempotent write. Merely accepting OrderStatus::Paid does not satisfy those rules.
For an example of why event identity and current state matter, see WishList Member webhook automation.
Test the contract at its boundaries
Run every supported backing value through the parser. Reject unknown strings, arrays, and null. Check that labels cover every case. Round-trip values through the real database column and exercise an older unsupported row.
For a public API, explicitly serialize the backing value into the response contract. Avoid letting an incidental object representation decide the wire format.
Should every constant become an enum?
No. Use an enum when a closed set and a dedicated type clarify the domain. Configuration keys, extensible plugin registries, and user-created categories may need another model.
If inconsistent status strings are causing production bugs, review the state and persistence boundaries before replacing names throughout the codebase.