Match Expressions

You met match briefly alongside switch. It deserves a lesson of its own, because it is not just a tidier switch: it is an expression that hands back a value, compares strictly, and refuses to silently do nothing. Those three traits make it the modern way to turn one value into another. The match expression has been part of PHP since version 8.0.

match Returns a Value

This is the difference that changes how you write code. A switch is a statement: it runs blocks and produces nothing you can capture, so each case has to echo or assign for itself. A match is an expression: the whole thing evaluates to a single value that you assign, return, or print directly. Compare the two shapes for the same task:

$label = "";
switch ($code) {
    case 404:
        $label = "Not Found";
        break;
    default:
        $label = "Unknown";
}

$label = match ($code) {
    404 => "Not Found",
    default => "Unknown",
};

Here is a full, runnable version. Notice how $message is assigned the result of the whole match, that arms use =>, and that the closing brace is followed by a semicolon because the statement is really $message = ...;.

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

Not Found

Because $statusCode is 404, PHP walks the arms top to bottom, finds the 404 arm, and the entire match becomes "Not Found". That value lands in $message. There is no break to forget and no way to accidentally fall into the next arm.

Strict Comparison, No Type Juggling

A switch compares with loose ==, so it quietly converts types before matching. A match compares with strict ===, so the value and the type must both agree. This is the single most useful safety property of match, and it is where it disagrees with switch on the same input. Predict this one before you run it:

<?php
$value = 5;
echo match ($value) {
    "5" => "string five",
    5   => "number five",
    default => "no match",
};

A switch would answer differently: switch (5) with a case "5" would fire, because loose == juggles the string into a number. That mismatch is a real bug source, so the rule of thumb is: when the exact type matters, reach for match.

Several Values Per Arm

When different inputs should produce the same result, list them on one arm separated by commas. It reads as “any of these.” Each value is still compared strictly, and the first arm that contains a match wins.

<?php
$level = "editor";
$access = match ($level) {
    "admin", "owner"   => "full",
    "member", "editor" => "limited",
    default            => "none",
};
echo $access;

limited

Both "admin" and "owner" map to "full", and both "member" and "editor" map to "limited". Grouping values this way replaces the old switch pattern of stacking bare case labels on top of each other to share a block, and it does it in one clear line.

Matching On Conditions With match(true)

So far every arm has tested “is the subject equal to this value?” But sometimes you need ranges or richer tests, not equality. The trick is to make the subject true and let each arm be a boolean condition. PHP finds the first arm whose condition evaluates to true. This turns match into a clean replacement for a long if/elseif ladder that produces a value.

Reading a grade from a score is three steps:

1. Set the subject to true
2. Write each threshold as a condition, strictest first
3. Let the first true condition supply the grade

<?php
$score = 82;
$grade = match (true) {
    $score >= 90 => "A",
    $score >= 80 => "B",
    $score >= 70 => "C",
    default      => "F",
};
echo $grade;

B

Order matters here, exactly like an if chain. What would this print if the $score >= 70 arm came first? It would print C, because 82 >= 70 is true and match stops at the first true arm, never reaching the B line. Always list the tightest condition first.

The same pattern handles any set of conditions, not just numbers. Each arm can be any boolean expression:

<?php
$temperature = 3;
echo match (true) {
    $temperature <= 0 => "freezing",
    $temperature < 15 => "cold",
    $temperature < 25 => "mild",
    default           => "warm",
};

cold

UnhandledMatchError Is a Feature

If no arm matches and there is no default, match throws an UnhandledMatchError instead of quietly doing nothing. A switch with no matching case and no default simply falls through and runs nothing, so a typo or a value you forgot slips by unnoticed. match refuses to guess. That loud failure is the point: it tells you about a case you did not handle rather than shipping a silent gap.

<?php
$httpStatus = 500;
try {
    $label = match ($httpStatus) {
        200 => "OK",
        404 => "Not Found",
    };
    echo $label;
} catch (\UnhandledMatchError $e) {
    echo "Caught: ", $e->getMessage();
}

Caught: Unhandled match case 500

There is no arm for 500 and no default, so PHP throws. Catching the error lets you see the message name the exact unhandled value. In real code you rarely catch it: you either add the missing arm or add a default so every input has a home.

Your Turn

<?php
$n = 30;

<?php
$n = 30;
echo match (true) {
    $n % 15 === 0 => "FizzBuzz",
    $n % 3 === 0  => "Fizz",
    $n % 5 === 0  => "Buzz",
    default       => (string) $n,
};

You have been calling functions like match-driven helpers with plain positional arguments. Next you will learn named arguments, an 8.0 feature that lets you pass values by parameter name so calls like createUser(name: "Billy", admin: true) read clearly and skip the optional parameters you do not care about.