Match Expression

Introduction

The previous lesson covered switch, PHP's classic tool for comparing a value against many possibilities. PHP 8 introduced a modern alternative called match, designed specifically to fix the sharp edges of switch: accidental fall-through, loose comparison, and the need to manually assign a result inside every branch.

In this lesson you will learn match's syntax, how it behaves differently from switch, how to match several values in a single arm, and what happens when nothing matches.

What is match?

match is an expression, not a statement — meaning it directly produces (and can be assigned or returned as) a value, rather than requiring you to echo or assign inside each branch. It was added in PHP 8.0 as a more predictable, more concise way to compare a single value against several possibilities.

Basic Syntax

A match expression takes a subject value, compares it against a list of arms (condition => result), and evaluates to the result of the first matching arm. A default arm can be written as an underscore, _, to catch every other case.

<?php
$statusCode = 404;

$message = match ($statusCode) {
    200 => "OK",
    301, 302 => "Redirect",
    404 => "Not Found",
    500 => "Server Error",
    default => "Unknown Status",
};

echo $message;

Not Found

Notice that each arm ends with a comma, not a break, and the whole expression can be assigned straight to $message.

match vs switch

match and switch solve a similar problem, but they behave quite differently under the hood.

Matching Multiple Values

Just like grouped switch cases, a single match arm can handle multiple values by separating them with commas. The arm runs if the subject strictly equals any one of the listed values.

<?php
$day = "Sat";

$type = match ($day) {
    "Mon", "Tue", "Wed", "Thu", "Fri" => "Weekday",
    "Sat", "Sun" => "Weekend",
};

echo $type;

Weekend

Unhandled Values

If none of the arms match and there is no default (written as _), PHP throws an UnhandledMatchError instead of silently doing nothing. This is a deliberate safety feature — it surfaces missing cases immediately instead of letting a bug hide.

<?php
$grade = "Z";

try {
    $result = match ($grade) {
        "A" => "Excellent",
        "B" => "Good",
    };
} catch (\UnhandledMatchError $e) {
    $result = "Error: " . $e->getMessage();
}

echo $result;

Error: Unhandled match case 'Z'

Side-by-Side Example

Here is the same logic — converting a numeric grade into a letter — written first as a switch statement, then as an equivalent match expression, so you can compare the two styles directly.

<?php
$score = 85;
$letter = "";

switch (true) {
    case $score >= 90:
        $letter = "A";
        break;
    case $score >= 80:
        $letter = "B";
        break;
    case $score >= 70:
        $letter = "C";
        break;
    default:
        $letter = "F";
        break;
}

echo $letter;

B

<?php
$score = 85;

$letter = match (true) {
    $score >= 90 => "A",
    $score >= 80 => "B",
    $score >= 70 => "C",
    default => "F",
};

echo $letter;

B

Both produce the same result, but the match version needs no break statements, no pre-declared $letter variable, and reads as a single direct assignment. Using match (true) with boolean arms is a common pattern for range-style comparisons like this one.

Common Mistakes

Best Practices

Frequently Asked Questions

Key Takeaways

Summary

The match expression is PHP 8's modern, safer alternative to switch. It compares strictly, never falls through, and returns a value directly, making your code shorter and less error-prone for value-comparison logic.