PHP Enums

When to use

• The user needs a fixed, closed set of named values such as order status, role, or state.
• The user wants to replace magic strings or class constants with a type-safe enum on PHP 8.1+.
• The user maps untrusted HTTP or API input to a known enum set and must reject invalid values.

When NOT to use

• Do not use this skill when the value set is open-ended or third parties must add values at runtime.
• Do not use enums when the target runtime is PHP 7.4 or 8.0; use class constants with allow-list validation instead.

Core guidance

• Choose backed enums when values are persisted or transmitted — Use a backed enum (enum Status: string) when values are stored in a database, serialized to JSON, or received from input. Use a pure enum when the values are purely in-memory tokens with no external representation.
• Use tryFrom for untrusted input, from for trusted values — Call tryFrom() on untrusted input and handle the null result; call from() only when the value originates from a trusted, already-validated source.

Quick recipe

1. Declare enum OrderStatus: string and list each case with its stored scalar value. (verify: OrderStatus::Paid->value === 'paid')
2. Add a label(): string method using match ($this) to map each case to display text. (verify: OrderStatus::Paid->label() returns the expected string)
3. At the controller boundary, resolve input with OrderStatus::tryFrom($input) and return 422 on null. (verify: Invalid input yields a 422 response, not a 500)

Best practices

• Use the generated Enum::cases() method to iterate all values (for dropdowns, validation lists, or seeding) instead of maintaining a separate array
• Have enums implement an interface when several enums must be used interchangeably (e.g
• Put value-specific behavior (labels, colors, transitions) in methods on the enum itself, typically with a match ($this) expression, rather than in external arrays

Anti-patterns

See references/anti-patterns.md.

Common mistakes

1. from() throws ValueError on unknown input — Calling Enum::from($userInput) on an unknown value throws an uncaught ValueError. Fix: Use tryFrom() and handle null, or wrap from() in a try/catch at trust boundaries.
2. Adding a case breaks non-exhaustive match — A match ($enum) without a default throws UnhandledMatchError when a new case is added. Fix: Rely on static analysis (PHPStan level 8) to flag non-exhaustive matches at build time rather than adding a catch-all default that hides new cases.
3. Pure enums do not serialize to a scalar — A pure (non-backed) enum has no ->value, so json_encode() emits an object, not a scalar. Fix: Use a backed enum when the value crosses a serialization boundary (JSON, DB, cache).

Version notes

• Enums introduced in PHP 8.1 (PHP >=8.1) — Enumerations (pure and backed), cases(), from(), and tryFrom() are available from PHP 8.1.
• Typed class constants complement enums in PHP 8.3 (PHP >=8.3) — From PHP 8.3, constants declared on an enum can be typed, tightening contracts shared via interfaces.
• PHP 8.5 enum refinements (PHP >=8.5) — PHP 8.5 refines enum constant handling; no code changes are required when migrating enum-heavy code from 8.4 to 8.5.

Security

• Validate enum input at the trust boundary — Treat any enum value sourced from HTTP, CLI, or third-party payloads as untrusted: resolve it with tryFrom() and reject null before it enters domain logic.

Testing

• Activation and decision behavior are verified in eval/scenarios/php/enums.yaml.

Additional resources

• references/anti-patterns.md
• references/core.md
• references/examples.md
• references/pitfalls.md
• references/recipes.md
• references/version-differences.md

Knowledge graph

Prerequisites: php/typed-properties
Related: php/attributes, php/class-constants, php/match-expression, php/value-objects