Skip to content
Tutorials Center
My learning

Topics

PHP Reference ยท Language Constructs and Statements

The match expression

Reference for the PHP 8 match expression: strict comparison, no fall-through, multiple conditions per arm, default and UnhandledMatchError.

match (added in PHP 8.0) compares a value against a list of arms and returns the result of the first arm that matches. Unlike switch, it is an expression, it compares with strict identity (===), and it never falls through, so no break is needed.

If no arm matches and there is no default, PHP throws an UnhandledMatchError. That makes forgotten cases visible instead of silent.

PHP
$label = match ($status) {
    200, 201 => "success",
    404      => "not found",
    default  => "other",
};

Try it

PHP Basic match with several conditions

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

PHP Strictness, match(true) and errors

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

Syntax

PHP
$result = match (expression) {
    condition1, condition2 => result1,
    condition3             => result2,
    default                => fallback,
};
Name Description
expression Evaluated once and compared strictly (===) with each condition.
condition One or more comma-separated expressions per arm (a trailing comma is allowed).
result A single expression, evaluated only if its arm is chosen. It can be a call, a throw expression, or any value.
default Optional catch-all arm.

Return value: the value of the matching arm.

Errors / Exceptions: UnhandledMatchError (a subclass of Error) when no arm matches. The message shows the unmatched value.

Usage notes

  • Strict comparison. match ("1") does not match an 1 arm. This removes the type-juggling surprises of switch.
  • No fall-through, no break. Each arm is independent. List several conditions in one arm with commas.
  • It is an expression. Assign it, return it, or pass it as an argument. Arms hold expressions, not statements; for several statements, call a function or use a closure.
  • Throwing in an arm. Since throw is an expression (PHP 8), default => throw new InvalidArgumentException("bad") works. See throw.
  • match (true). Arms are tested in order and the first true condition wins, giving a readable range test. Remember each condition must be exactly true, so use comparisons that return booleans.
  • Lazy evaluation. Only the conditions up to the first match, and the chosen result, are evaluated.
  • Not exhaustive checking by itself. The error appears at runtime. With enums, listing every case lets static analysers prove completeness.
  • Works well with enums (Suit::Hearts => ...).
  • Semicolon required after the closing brace when used as a statement or in an assignment.