match Expression (PHP 8.0)

Also Known As

TL;DR

Explanation

The match expression was introduced in PHP 8.0 as a replacement for switch with three key improvements: it uses strict (===) comparison instead of loose (==), each arm is an expression returning a value (no break needed), and it throws an UnhandledMatchError if no arm matches (unlike switch which silently falls through). Multiple conditions can be comma-separated in a single arm. match is particularly useful for mapping one value to another without mutation.

Common Misconception

Why It Matters

Common Mistakes

• Using match when you need fall-through across multiple conditions — match has no fall-through by design.
• Forgetting match throws UnhandledMatchError for unmatched values — always include a default arm if exhaustiveness is not guaranteed.
• Using match for complex multi-statement logic per arm — it returns a single expression, use if/else for multi-line branches.
• Assuming match works like switch for loose comparisons — match is always strict (===).

Code Examples

// switch with type coercion — '1' matches 1:
switch ($status) {
    case 1: return 'active'; // '1' also matches — loose comparison
    case 0: return 'inactive';
}

// match uses strict comparison:
return match($status) {
    1 => 'active',
    0 => 'inactive',
    default => throw new UnhandledMatchError(),
};

// match is strict (===), exhaustive, and expression-based
$label = match($order->status) {
    'pending'   => 'Awaiting payment',
    'paid'      => 'Processing',
    'shipped'   => 'On the way',
    'cancelled' => 'Cancelled',
    default     => throw new \UnexpectedValueException("Unknown status: {$order->status}"),
};

// No default = UnhandledMatchError on unmatched value — catches missing cases at runtime
// PHPStan/Psalm can also verify exhaustiveness at analysis time

References

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

Tags

Related Terms