match() Exhaustiveness & UnhandledMatchError

Also Known As

TL;DR

Explanation

Unlike switch, PHP 8's match expression is strict in two ways: it uses strict comparison (===, not ==) and throws an UnhandledMatchError if no arm matches and there is no default. This transforms previously silent bugs — a switch with a missing case that fell through silently — into immediate, detectable failures. Add a default arm to handle unexpected values explicitly, or let the error surface during testing rather than silently misbehave in production. Static analysers (PHPStan, Psalm) can detect non-exhaustive match expressions against enum cases (PHP 8.1+), enforcing completeness at analysis time. Combine match with enum to get compile-time exhaustiveness guarantees.

Common Misconception

Why It Matters

Common Mistakes

• Not providing a default arm for match expressions that may receive unexpected values in production.
• Assuming match and switch are equivalent — match uses strict comparison (===), switch uses loose (==).
• Not using match as a return value — it is an expression, eliminating the need for break and temporary variables.
• Using match where the value space is open-ended (user input) without a default — UnhandledMatchError in production.

Code Examples

// switch with loose comparison and silent fallthrough:
switch ($code) {
    case '200': $status = 'OK'; break;   // '200' == 200 in switch
    case '404': $status = 'Not Found';   // Missing break — falls through!
    case '500': $status = 'Error'; break;
}

// match — strict, no fallthrough, expression:
$status = match((int)$code) {
    200 => 'OK', 404 => 'Not Found', 500 => 'Error',
    default => throw new InvalidArgumentException("Unknown code: $code")
};

$label = match($status) {
  Status::Active   => 'Active',
  Status::Inactive => 'Inactive',
  // UnhandledMatchError thrown for any other value — caught in tests
};

Tags

Related Terms

References

• https://www.php.net/manual/en/control-structures.match.php