array ( 0 => 'index.php', 1 => 'PHP Manual', ), 'head' => array ( 0 => 'UTF-8', 1 => 'pt_BR', ), 'this' => array ( 0 => 'control-structures.match.php', 1 => 'match', ), 'up' => array ( 0 => 'language.control-structures.php', 1 => 'Estruturas de Controle', ), 'prev' => array ( 0 => 'control-structures.switch.php', 1 => 'switch', ), 'next' => array ( 0 => 'control-structures.declare.php', 1 => 'declare', ), 'alternatives' => array ( ), 'source' => array ( 'lang' => 'pt_BR', 'path' => 'language/control-structures/match.xml', ), ); $setup["toc"] = $TOC; $setup["toc_deprecated"] = $TOC_DEPRECATED; $setup["parents"] = $PARENTS; manual_setup($setup); ?>
(PHP 8)
A expressão match
ramifica a avaliação baseada em uma
verificação de identidade de um valor.
Semelhante a uma declaração switch
, uma
expressão match
possui uma expressão sujeito que é
comparada com múltiplas alternativas. Ao contrário da switch
,
ela irá avaliar para um valor assim como as expressões ternárias.
Diferente da switch
, a comparação é uma verificação de identidade
(===
) em vez de uma comparação de equalidade fraca (==
).
Expressões match estão diponíveis a partir do PHP 8.0.0.
Exemplo #1 Estrutura de uma expressão match
<?php
$valor_de_retorno = match (expressao_sujeito) {
expressao_condicional_unica => expressao_de_retorno,
expressao_condicional1, expressao_condicional2 => expressao_de_retorno,
};
?>
Exemplo #2 Basic match
usage
<?php
$comida = 'bolo';
$valor_de_retorno = match ($comida) {
'apple' => 'Essa comida é uma maçã',
'bar' => 'Essa comida é um bar',
'bolo' => 'Essa comida é um bolo',
};
var_dump($valor_de_retorno);
?>
O exemplo acima produzirá:
string(19) "Essa comida é um bolo"
Nota: O resultado de uma expressão
match
não precisa ser usado.
Nota: Uma expressão
match
deve ser terminada por um ponto e vírgula;
.
A expressão match
é similar a uma
declaração switch
mas tem algumas diferenças importantes:
match
compara valores estritamente (===
) em vez
de frouxamente como a declaração switch faz.
match
retorna um valor.
match
não seguem para casos posteriores da maneira
que declarações switch
seguem.
match
deve ser exaustiva.
Assim como as declarações switch
, expressões
match
são executadas braço de correspondência por braço de correspondência.
No início, nenhum código é executado.
A expressões condicionais só são avaliadas se todas as expressões condicionais
anteriores não corresponderem à expressão sujeito.
Apenas a expressão de retorno pertencente à expressão condicional
de correspondência será avaliada.
<?php
$resultado = match ($x) {
foo() => ...,
$this->bar() => ..., // $this->bar() não é chamado se foo() === $x
$this->baz => beep(), // beep() não é chamado a não ser que $x === $this->baz
// etc.
};
?>
Braços da expressão match
podem conter múltiplas expressões
separadas por uma vírgula. Isso é um OR lógico, e é uma forma abreviada para múltimplos
braços de correspondência com o mesmo lado direito.
<?php
$resultado = match ($x) {
// Este braço de correspondência:
$a, $b, $c => 5,
// É equivalente a estes três braços de correspondência:
$a => 5,
$b => 5,
$c => 5,
};
?>
Um caso especial é o padrão default
.
Esse padrão atende a qualquer coisa que não tenha sido atendida anteriormente.
Por exemplo:
<?php
$resultadoDaExpressao = match ($condicao) {
1, 2 => foo(),
3, 4 => bar(),
default => baz(),
};
?>
Nota: Múltiplos padrões default irão emitir um erro
E_FATAL_ERROR
.
Uma expressão match
deve ser exaustiva. Se a
expressão sujeito não for tratada por nenhum braço de correspondência um
UnhandledMatchError é lançado.
Exemplo #3 Exemplo de uma expressão match não tratada
<?php
$condicao = 5;
try {
match ($condicao) {
1, 2 => foo(),
3, 4 => bar(),
};
} catch (\UnhandledMatchError $e) {
var_dump($e);
}
?>
O exemplo acima produzirá:
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 }
É possível usar uma expressão match
para tratar
casos condicionais sem identidade usando true
como a expressão
sujeito.
Exemplo #4 Usando uma expressão match generalizada para ramificar com base em intervalos de inteiros
<?php
$idade = 23;
$resultado = match (true) {
$idade >= 65 => 'senhor',
$idade >= 25 => 'adulto',
$idade >= 18 => 'adolescente',
default => 'criança',
};
var_dump($resultado);
?>
O exemplo acima produzirá:
string(11) "adolescente"
Exemplo #5 Usando uma expressão match generalizada para ramificar com base no conteúdo de strings
<?php
$texto = 'Bienvenue chez nous';
$resultado = match (true) {
str_contains($texto, 'Welcome') || str_contains($texto, 'Hello') => 'en',
str_contains($texto, 'Bienvenue') || str_contains($texto, 'Bonjour') => 'fr',
// ...
};
var_dump($resultado);
?>
O exemplo acima produzirá:
string(2) "fr"