PHP match Expression: match vs switch, match(true)

match ($value) { ... } compares a value against a list of arms with strict === and returns the result of the first arm that matches. Several values can share an arm, default catches the rest, and if nothing matches PHP throws an UnhandledMatchError.

<?php
$status = 404;

$message = match ($status) {
    200, 201, 204 => 'Success',
    301, 302 => 'Redirect',
    404 => 'Not found',
    500 => 'Server error',
    default => 'Unknown status',
};

echo $message;

Note the semicolon after the closing brace: match is an expression, like 1 + 2, so the whole thing is one assignment statement. Each arm is values => result, separated by commas, and a trailing comma after the last arm is allowed.

Multiple values in one arm

List the values with commas. The arm matches if the subject is identical (===) to any of them.

<?php
function dayType(string $day): string
{
    return match ($day) {
        'sat', 'sun' => 'weekend',
        'mon', 'tue', 'wed', 'thu', 'fri' => 'weekday',
        default => 'not a day',
    };
}

foreach (['sat', 'wed', 'holiday'] as $d) {
    echo "$d: ", dayType($d), "\n";
}

Returning match directly from a function, as here, is the most common way to use it.

match vs switch

The same mapping written both ways, with one input that shows the biggest difference: comparison. switch uses ==, so the string "1" matches case 1. match uses ===, so it does not.

<?php
$input = "1"; // a string, as it would come from a form

switch ($input) {
    case 1:
        $fromSwitch = 'one';
        break;
    default:
        $fromSwitch = 'other';
}

$fromMatch = match ($input) {
    1 => 'one',
    default => 'other',
};

echo "switch: $fromSwitch\n";
echo "match:  $fromMatch\n";
echo "match after (int): ", match ((int) $input) { 1 => 'one', default => 'other' }, "\n";

Use match when you are turning one value into another. Keep switch when a branch needs several statements or when fallthrough is the point; the switch page has both cases.

UnhandledMatchError: when no arm matches

Without a default arm, a value that matches nothing is an error, not a silent null. That is a feature: a new status code or a typo fails loudly instead of slipping through.

<?php
// This throws an UnhandledMatchError on purpose
$size = 'XL';

echo match ($size) {
    'S' => 'small',
    'M' => 'medium',
    'L' => 'large',
};

PHP stops with PHP Fatal error: Uncaught UnhandledMatchError: Unhandled match case of type string. A development setup (with zend.exception_ignore_args off) names the value instead: Unhandled match case 'XL'. Fix it either by adding default => 'other', or by catching the error where an unknown value is expected:

<?php
function sizeName(string $size): string
{
    return match ($size) {
        'S' => 'small',
        'M' => 'medium',
        'L' => 'large',
    };
}

foreach (['M', 'XL'] as $size) {
    try {
        echo sizeName($size), "\n";
    } catch (\UnhandledMatchError $e) {
        echo "Unknown size: $size\n";
    }
}

match(true) for ranges and conditions

match compares the subject with each arm, so if the subject is true, every arm can be a condition. The first condition that evaluates to exactly true wins.

<?php
function ageGroup(int $age): string
{
    return match (true) {
        $age < 0 => throw new InvalidArgumentException('Age cannot be negative'),
        $age < 13 => 'child',
        $age < 18 => 'teenager',
        $age < 65 => 'adult',
        default => 'senior',
    };
}

foreach ([8, 15, 40, 70] as $age) {
    echo "$age: ", ageGroup($age), "\n";
}

try {
    ageGroup(-1);
} catch (InvalidArgumentException $e) {
    echo "Error: ", $e->getMessage(), "\n";
}

Two details in that block. throw is an expression since PHP 8, so it can be the result of an arm. And because the comparison is strict, each condition must return a real boolean: an arm like $name => ... never matches true even when $name is a non-empty string. Only the arm that matches is evaluated, so the throw runs only for a negative age.

match with enums

match and enums fit together: inside an enum method, match ($this) maps each case to a value. See PHP enums for enums themselves.

<?php
enum Suit
{
    case Hearts;
    case Diamonds;
    case Clubs;
    case Spades;

    public function color(): string
    {
        return match ($this) {
            Suit::Hearts, Suit::Diamonds => 'Red',
            Suit::Clubs, Suit::Spades => 'Black',
        };
    }
}

foreach (Suit::cases() as $suit) {
    echo $suit->name, " is ", $suit->color(), "\n";
}

No default here on purpose. If someone adds a fifth case later, calling color() on it throws instead of returning a wrong color.

Several statements in one arm

An arm holds one expression, so 'save' => { ...; ... } is not valid PHP. Move the work into a function and call it from the arm. The functions of the arms that do not match are never called.

<?php
function exportCsv(array $rows): string
{
    $lines = array_map(fn($r) => implode(',', $r), $rows);
    return implode("\n", $lines);
}

function exportJson(array $rows): string
{
    return json_encode($rows);
}

$rows = [['Ada', 36], ['Linus', 28]];
$format = 'csv';

echo match ($format) {
    'csv' => exportCsv($rows),
    'json' => exportJson($rows),
    default => "Unsupported format: $format",
};

Change $format to 'json' or 'xml' and run it again.