match

    (PHP 8)

    The match expression branches evaluation based on an identity check of a value. Similarly to a switch statement, a match expression has a subject expression that is compared against multiple alternatives. Unlike switch, it will evaluate to a value much like ternary expressions. Unlike switch, the comparison is an identity check (===) rather than a weak equality check (==). Match expressions are available as of PHP 8.0.0.

    Приклад #1 Structure of a match expression

    <?php
    $return_value     = match (subject_expression) {
    single_conditional_expression => return_expression,
    conditional_expression1, conditional_expression2 => return_expression,
    };
    ?>

    Приклад #2 Basic match usage

    <?php
    $food     = 'cake';

    $return_value = match ($food) {
    'apple' => 'This food is an apple',
    'bar' => 'This food is a bar',
    'cake' => 'This food is a cake',
    };

    var_dump($return_value);
    ?>

    Поданий вище приклад виведе:

    string(19) "This food is a cake"

    Приклад #3 Example of using match with comparison operators

    <?php
    $age     = 18;

    $output = match (true) {
    $age < 2 => "Baby",
    $age < 13 => "Child",
    $age <= 19 => "Teenager",
    $age >= 40 => "Old adult",
    $age > 19 => "Young adult",
    };

    var_dump($output);
    ?>

    Поданий вище приклад виведе:

    string(8) "Teenager"

    Зауваження: The result of a match expression does not need to be used.

    Зауваження: A match expression must be terminated by a semicolon ;.

    The match expression is similar to a switch statement but has some key differences:

    • A match arm compares values strictly (===) instead of loosely as the switch statement does.
    • A match expression returns a value.
    • match arms do not fall-through to later cases the way switch statements do.
    • A match expression must be exhaustive.

    As switch statements, match expressions are executed match arm by match arm. In the beginning, no code is executed. The conditional expressions are only evaluated if all previous conditional expressions failed to match the subject expression. Only the return expression corresponding to the matching conditional expression will be evaluated. For example:

    <?php
    $result     = match ($x) {
    foo() => ...,
    $this->bar() => ..., // $this->bar() isn't called if foo() === $x
    $this->baz => beep(), // beep() isn't called unless $x === $this->baz
    // etc.
    };
    ?>

    match expression arms may contain multiple expressions separated by a comma. That is a logical OR, and is a short-hand for multiple match arms with the same right-hand side.

    <?php
    $result     = match ($x) {
    // This match arm:
    $a, $b, $c => 5,
    // Is equivalent to these three match arms:
    $a => 5,
    $b => 5,
    $c => 5,
    };
    ?>

    A special case is the default pattern. This pattern matches anything that wasn't previously matched. For example:

    <?php
    $expressionResult     = match ($condition) {
    1, 2 => foo(),
    3, 4 => bar(),
    default =>     baz(),
    };
    ?>

    Зауваження: Multiple default patterns will raise a E_FATAL_ERROR error.

    A match expression must be exhaustive. If the subject expression is not handled by any match arm an UnhandledMatchError is thrown.

    Приклад #4 Example of an unhandled match expression

    <?php
    $condition     = 5;

    try {
    match (    $condition) {
    1, 2 => foo(),
    3, 4 => bar(),
    };
    } catch (    \UnhandledMatchError $e) {
    var_dump($e);
    }
    ?>

    Поданий вище приклад виведе:

    object(UnhandledMatchError)#1 (7) {
  ["message":protected]=>
  string(33) "Unhandled match value of type int"
  ["string":"Error":private]=>
  string(0) ""
  ["code":protected]=>
  int(0)
  ["file":protected]=>
  string(9) "/in/ICgGK"
  ["line":protected]=>
  int(6)
  ["trace":"Error":private]=>
  array(0) {
  }
  ["previous":"Error":private]=>
  NULL
}

    Using match expressions to handle non identity checks

    It is possible to use a match expression to handle non-identity conditional cases by using true as the subject expression.

    Приклад #5 Using a generalized match expressions to branch on integer ranges

    <?php

    $age     = 23;

    $result = match (true) {
    $age >= 65 => 'senior',
    $age >= 25 => 'adult',
    $age >= 18 => 'young adult',
    default =>     'kid',
    };

    var_dump($result);
    ?>

    Поданий вище приклад виведе:

    string(11) "young adult"

    Приклад #6 Using a generalized match expressions to branch on string content

    <?php

    $text     = 'Bienvenue chez nous';

    $result = match (true) {
    str_contains($text, 'Welcome') || str_contains($text, 'Hello') => 'en',
    str_contains($text, 'Bienvenue') || str_contains($text, 'Bonjour') => 'fr',
    // ...
    };

    var_dump($result);
    ?>

    Поданий вище приклад виведе:

    string(2) "fr"

    Improve This Page

    Learn How To Improve This Page • Submit a Pull Request • Report a Bug
    ＋add a note

    User Contributed Notes 9 notes

    up
    92
    darius dot restivan at gmail dot com
    3 years ago
    This will allow for a nicer FizzBuzz solution:

    <?php

    function fizzbuzz($num) {
    print match (    0) {
    $num % 15 => "FizzBuzz" . PHP_EOL,
    $num % 3 => "Fizz" . PHP_EOL,
    $num % 5 => "Buzz" . PHP_EOL,
    default =>     $num . PHP_EOL,
    };
    }

    for (    $i = 0; $i <=100; $i++)
    {
    fizzbuzz($i);
    }
    up
    73
    Anonymous
    3 years ago
    <?php
    function days_in_month(string $month, $year): int
    {
    return match(    strtolower(substr($month, 0, 3))) {
    'jan' => 31,
    'feb' => is_leap($year) ? 29 : 28,
    'mar' => 31,
    'apr' => 30,
    'may' => 31,
    'jun' => 30,
    'jul' => 31,
    'aug' => 31,
    'sep' => 30,
    'oct' => 31,
    'nov' => 30,
    'dec' => 31,
    default => throw new     InvalidArgumentException("Bogus month"),
    };
    }
    ?>

    can be more concisely written as

    <?php
    function days_in_month(string $month, $year): int
    {
    return match(    strtolower(substr($month, 0, 3))) {
    'apr', 'jun', 'sep', 'nov' => 30,
    'jan', 'mar', 'may', 'jul', 'aug', 'oct', 'dec' => 31,
    'feb' => is_leap($year) ? 29 : 28,
    default => throw new     InvalidArgumentException("Bogus month"),
    };
    }
    ?>
    up
    54
    Hayley Watson
    3 years ago
    As well as being similar to a switch, match expressions can be thought of as enhanced lookup tables — for when a simple array lookup isn't enough without extra handling of edge cases, but a full switch statement would be overweight.

    For a familiar example, the following
    <?php

    function days_in_month(string $month): int
    {
    static     $lookup = [
    'jan' => 31,
    'feb' => 0,
    'mar' => 31,
    'apr' => 30,
    'may' => 31,
    'jun' => 30,
    'jul' => 31,
    'aug' => 31,
    'sep' => 30,
    'oct' => 31,
    'nov' => 30,
    'dec' => 31
    ];

    $name = strtolower(substr($name, 0, 3));

    if(isset(    $lookup[$name])) {
    if(    $name == 'feb') {
    return     is_leap($year) ? 29 : 28;
    } else {
    return     $lookup[$name];
    }
    }
    throw new     InvalidArgumentException("Bogus month");
    }

    ?>

    with the fiddly stuff at the end, can be replaced by

    <?php
    function days_in_month(string $month): int
    {
    return match(    strtolower(substr($month, 0, 3))) {
    'jan' => 31,
    'feb' => is_leap($year) ? 29 : 28,
    'mar' => 31,
    'apr' => 30,
    'may' => 31,
    'jun' => 30,
    'jul' => 31,
    'aug' => 31,
    'sep' => 30,
    'oct' => 31,
    'nov' => 30,
    'dec' => 31,
    default => throw new     InvalidArgumentException("Bogus month"),
    };
    }
    ?>

    Which also takes advantage of "throw" being handled as of PHP 8.0 as an expression instead of a statement.
    up
    10
    thomas at zuschneid dot de
    1 year ago
    While match allows chaining multiple conditions with ",", like:
    <?php
    $result     = match ($source) {
    cond1, cond2 => val1,
    default =>     val2
    };
    ?>
    it seems not valid to chain conditions with default, like:
    <?php
    $result     = match ($source) {
    cond1 => val1,
    cond2, default => val2
    };
    ?>
    up
    6
    Sbastien
    1 year ago
    I use match instead of storing PDOStatement::rowCount() result and chaining if/elseif conditions or use the ugly switch/break :

    <?php

    $sql     = <<<SQL
     INSERT INTO ...
    ON DUPLICATE KEY UPDATE ...
     SQL;

    $upkeep = $pdo->prepare($sql);

    $count_untouched = 0;
    $count_inserted = 0;
    $count_updated = 0;

    foreach (    $data as $record) {
    $upkeep->execute($record);
    match (    $upkeep->rowCount()) {
    0 => $count_untouched++,
    1 => $count_inserted++,
    2 => $count_updated++,
    };
    }

    echo     "Untouched rows : {$count_untouched}\r\n";
    echo     "Inserted rows : {$count_inserted}\r\n";
    echo     "Updated rows : {$count_updated}\r\n";
    up
    7
    tolga dot ulas at tolgaulas dot com
    8 months ago
    Yes it currently does not support code blocks but this hack works:

    match ($foo){
    'bar'=>(function(){
    echo "bar";
    })(),
    default => (function(){
    echo "baz";
    })()
    };
    up
    13
    php at joren dot dev
    2 years ago
    If you want to execute multiple return expressions when matching a conditional expression, you can do so by stating all return expressions inside an array.

    <?php
    $countries     = ['Belgium', 'Netherlands'];
    $spoken_languages = [
    'Dutch' => false,
    'French' => false,
    'German' => false,
    'English' => false,
    ];

    foreach (    $countries as $country) {
    match(    $country) {
    'Belgium' => [
    $spoken_languages['Dutch'] = true,
    $spoken_languages['French'] = true,
    $spoken_languages['German'] = true,
    ],
    'Netherlands' => $spoken_languages['Dutch'] = true,
    'Germany' => $spoken_languages['German'] = true,
    'United Kingdom' => $spoken_languages['English'] = true,
    };
    }

    var_export($spoken_languages);
    // array ( 'Dutch' => true, 'French' => true, 'German' => true, 'English' => false, )

    ?>
    up
    4
    mark at manngo dot net
    2 years ago
    While you can’t polyfill a language construct, you can mimic the basic behaviour with a simple array.

    Using example 2 above:

    <?php
    $food     = 'apple';
    $return_value = match ($food) {
    'apple' => 'This food is an apple',
    'bar' => 'This food is a bar',
    'cake' => 'This food is a cake',
    };
    print     $return_value;
    ?>

    … you can get something similar with:

    <?php
    $food     = 'apple';
    $return_value = [
    'apple' => 'This food is an apple',
    'bar' => 'This food is a bar',
    'cake' => 'This food is a cake',
    ][    $food];
    print     $return_value;
    ?>
    up
    1
    tm
    3 years ago
    If you are using a match expression for non-identity checks as described above make sure whatever you are using is actually returning `true` on success.

    Quite often you rely on truthy vs. falsy when using if conditions and that will not work for match (for example `preg_match`). Casting to bool will solve this issue.
    ＋add a note
    To Top