Match

caution

Match expression is natively supported since PHP 8 version. We recommend using that instead of the munus match. Munus match is a great option for PHP 7 support.

Match is an expression similar to the switch statement. It has a subject expression that is compared against multiple alternatives. All of the alternatives return value, which is the result of expression if the alternative is matched.

Construction#

To use match, you need to specify some alternatives. Each match expression can include multiple normal cases and one default case.

PHP 7
PHP 8

$result = matchValue('value')->of(
    caseOf('value', 'first case matched'),
    defaultOf('default case matched')
);

There are four types of cases in munus:

caseOf($value, $other) - it's the case that compare value, and returns other value if is matched
caseCall($value, callable $callable) - it's the case that compare value, and returns the result of executed callable
defaultOf($other) - it's the default case that is matched if any of others are not, and returns other value
defaultCall(callable $callable) - it's the default case that is matched if any of others are not, and returns the result of executed callable

Callable#

Both munus and native match allow using callables as results.

PHP 7
PHP 8

$result = matchValue($x)->of(
    caseCall(5, function ($x) { return $x * 2; }),
    defaultCall(function ($x) { return $x / 2; })
);

There is a small difference between them. In the native match, you can put the expression that in the normal way, should be run, but in the match, it will be executed only if the alternative is matched. You can get the same behavior in munus match. It's not the most beautiful solution, but it works the same.

PHP 7
PHP 8

$result = matchValue($x)->of(
    caseCall(5, function ($x) { return foo(); }),
    defaultCall(function ($x) { return bar(); })
);

Exception#

A match statement requires to match at least one of the alternatives, if there is no match, it throws an exception.

PHP 7
PHP 8

try {
    matchValue(5)->of(
        caseOf(4, 'foo'),
        caseOf(6, 'bar')
    );
} catch (\Munus\Exception\MatchNotFoundException $e) {
    var_dump($e);
}

Predicates#

Munus provides some predicates, that helps with building alternatives.

isIn(iterable $values) - accepts iterable of any type, and check if value is matched to any of them
isInstanceOf(string $className) - accepts the class name, and check if the value is the instance of it
isNull() - check if the value is null
isNotNull() - check if the value is not null
isValue($value) - accepts value of any type and check if the values are same
isAllOf(Predicate ...$predicates) - accepts iterable of predicates, and check if all of them are matched
isAnyOf(Predicate ...$predicates) - accepts iterable of predicates, and check if any of them is matched
isNoneOf(Predicate ...$predicates) - accepts iterable of predicates, and check if none of them are matched

Usage#

In PHP 8 where the match is natively supported, you can also use predicates in expressions. Every predicate is the implementation of the Munus\Match\Predicate interface. This interface has meet($value): bool method, which executes the predicate, and returns bool value.
It's not always more readable solution, but you can choose which you want.

IsIn#

PHP 7
PHP 8
PHP 8 (predicates)

$result = matchValue($x)->of(
    caseOf(isIn($a, $b, $c), 5)
);

IsInstanceOf#

PHP 7
PHP 8
PHP 8 (predicates)

$result = matchValue($x)->of(
    caseOf(isInstanceOf(DateTime::class), 5)
);

IsAllOf#

PHP 7
PHP 8
PHP 8 (predicates)

$foo = 'bar';
$result = matchValue($foo)->of(
    caseOf(isAllOf(isNotNull(), isValue('bar'))), 5)
);

IsAnyOf#

PHP 7
PHP 8
PHP 8 (predicates)

$result = matchValue($x)->of(
    caseOf(isAnyOf(isNotNull(), isInstanceOf(DateTime::class)), 5)
);

IsNoneOf#

PHP 7
PHP 8
PHP 8 (predicates)

$result = matchValue($x)->of(
    caseOf(isNoneOf(isNotNull(), isInstanceOf(DateTime::class)), 5)
);