Expressão match no PHP: match ou switch e match(true)

match ($value) { ... } compara um valor com uma lista de braços usando o estrito === e retorna o resultado do primeiro braço que bate. Vários valores podem dividir um braço, default pega o resto, e se nada bater o PHP lança um 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;

Repare no ponto e vírgula depois da chave de fechamento: match é uma expressão, como 1 + 2, então o conjunto todo é uma instrução de atribuição. Cada braço é valores => resultado, separados por vírgulas, e uma vírgula depois do último braço é permitida.

Vários valores num braço

Liste os valores com vírgulas. O braço bate se o sujeito for idêntico (===) a qualquer um deles.

<?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";
}

Retornar o match direto de uma função, como aqui, é o jeito mais comum de usá-lo.

match ou switch

O mesmo mapeamento escrito dos dois jeitos, com uma entrada que mostra a maior diferença: a comparação. O switch usa ==, então a string "1" bate com case 1. O match usa ===, então não bate.

<?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 quando você está transformando um valor em outro. Mantenha o switch quando um ramo precisa de várias instruções ou quando o fallthrough é o objetivo; a página sobre switch tem os dois casos.

UnhandledMatchError: quando nenhum braço bate

Sem um braço default, um valor que não bate com nada é um erro, não um null silencioso. Isso é uma vantagem: um novo código de status ou um erro de digitação falha de forma visível em vez de passar despercebido.

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

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

O PHP para com PHP Fatal error: Uncaught UnhandledMatchError: Unhandled match case of type string. Uma configuração de desenvolvimento (com zend.exception_ignore_args desligado) mostra o valor: Unhandled match case 'XL'. Corrija adicionando default => 'other', ou capturando o erro onde um valor desconhecido é esperado:

<?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) para intervalos e condições

O match compara o sujeito com cada braço, então se o sujeito for true, cada braço pode ser uma condição. A primeira condição que avaliar exatamente como true vence.

<?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";
}

Dois detalhes nesse bloco. throw é uma expressão desde o PHP 8, então pode ser o resultado de um braço. E como a comparação é estrita, cada condição precisa retornar um booleano de verdade: um braço como $name => ... nunca bate com true, mesmo quando $name é uma string não vazia. Só o braço que bate é avaliado, então o throw só roda para uma idade negativa.

match com enums

match e enums combinam: dentro de um método de enum, match ($this) mapeia cada caso para um valor. Veja enums no PHP para os enums em si.

<?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";
}

Sem default aqui, de propósito. Se alguém adicionar um quinto caso depois, chamar color() nele lança um erro em vez de retornar uma cor errada.

Várias instruções num braço

Um braço contém uma expressão, então 'save' => { ...; ... } não é PHP válido. Mova o trabalho para uma função e chame-a a partir do braço. As funções dos braços que não batem nunca são chamadas.

<?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",
};

Mude $format para 'json' ou 'xml' e rode de novo.