archived-doc-es/language/control-structures/match.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: 17502ebe0691a84e7d0738c13e8c1061dde98de7 Maintainer: PhilDaiguille Status: ready -->
<!-- Reviewed: yes -->

<sect1 xml:id="control-structures.match" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <title>match</title>
 <?phpdoc print-version-for="match"?>
 <para>
  La expresión <literal>match</literal> permite realizar una evaluación basada en el
  control de identidad de un valor.
  De manera similar a una instrucción <literal>switch</literal>, una expresión
  <literal>match</literal> tiene una expresión sujeto que es
  comparada con varias alternativas. A diferencia de <literal>switch</literal>,
  se evalúa a un valor, como las expresiones ternarias.
  A diferencia de <literal>switch</literal>, la comparación es una verificación de identidad
  (<code>===</code>) en lugar de un control de igualdad débil (<code>==</code>).
  Las expresiones Match están disponibles a partir de PHP 8.0.0.
 </para>

 <example>
  <title>Estructura de una expresión <literal>match</literal></title>
  <programlisting role="php">
<![CDATA[
<?php
$return_value = match (subject_expression) {
    single_conditional_expression => return_expression,
    conditional_expression1, conditional_expression2 => return_expression,
};
?>
]]>
  </programlisting>

   <example>
  <title>Uso básico de las expresiones <literal>match</literal></title>
    <programlisting role="php">
<![CDATA[
<?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);
?>
]]>
  </programlisting>
  &example.outputs;
   <screen>
<![CDATA[
string(19) "This food is a cake"
]]>
   </screen>
  </example>

  <example>
   <title>Ejemplo de uso de <literal>match</literal> con operadores de comparación</title>
    <programlisting role="php">
<![CDATA[
<?php
$age = 18;

$output = match (true) {
    $age < 2 => "Bebé",
    $age < 13 => "Niño",
    $age <= 19 => "Adolescente",
    $age >= 40 => "Adulto mayor",
    $age > 19 => "Adulto joven",
};

var_dump($output);
?>
]]>
  </programlisting>
  &example.outputs;
   <screen>
<![CDATA[
string(12) "Adolescente"
]]>
   </screen>
  </example>

  <note>
   <simpara>
    El resultado de una expresión <literal>match</literal> no necesita ser utilizado.
   </simpara>
  </note>
  <note>
   <simpara>
    Cuando una expresión <literal>match</literal> se utiliza como una expresión autónoma,
    <emphasis>debe</emphasis> ser terminada
    por un punto y coma <literal>;</literal>.
   </simpara>
  </note>
 </example>

 <para>
  La expresión <literal>match</literal> es similar a una instrucción
  <literal>switch</literal> pero presenta algunas diferencias esenciales:

  <itemizedlist>
   <listitem>
    <simpara>
     Una expresión <literal>match</literal> compara los valores de manera estricta (<code>===</code>)
     y no de manera débil como lo hace la instrucción switch.
    </simpara>
   </listitem>
   <listitem>
    <simpara>
     Una expresión <literal>match</literal> devuelve un valor.
    </simpara>
   </listitem>
   <listitem>
    <simpara>
     Las expresiones <literal>match</literal> no pasan a los casos siguientes como lo hacen las
     instrucciones <literal>switch</literal>.
    </simpara>
   </listitem>
   <listitem>
    <simpara>
     Una expresión <literal>match</literal> debe ser exhaustiva.
    </simpara>
   </listitem>
  </itemizedlist>
 </para>

 <para>
  Al igual que las instrucciones <literal>switch</literal>, las expresiones <literal>match</literal>
  se ejecutan brazo por brazo. Al principio, ningún código se ejecuta.
  Las expresiones condicionales solo se evalúan si todas las expresiones condicionales
  anteriores no coinciden con la expresión del sujeto.
  Solo la expresión de retorno correspondiente a la expresión condicional correspondiente será evaluada.
  Por ejemplo:
  <informalexample>
   <programlisting role="php">
<![CDATA[
<?php
$result = match ($x) {
    foo() => 'value',
    $this->bar() => 'value', // $this->bar() no es llamado si foo() === $x
    $this->baz => beep(), // beep() no es llamado a menos que $x === $this->baz
    // etc.
};
?>
]]>
   </programlisting>
  </informalexample>
 </para>

 <para>
  Los brazos de la expresión de <literal>match</literal> pueden contener múltiples expresiones
  separadas por una coma. Se trata de un OU lógico y de una abreviación para múltiples brazos
  que utilizan la misma expresión como resultado.
 </para>
 <para>
  <informalexample>
   <programlisting role="php">
<![CDATA[
<?php
$result = match ($x) {
    // Este brazo
    $a, $b, $c => 5,
    // Es equivalente a estos tres brazos:
    $a => 5,
    $b => 5,
    $c => 5,
};
?>
]]>
   </programlisting>
  </informalexample>
 </para>
 <para>
  El patrón <literal>default</literal> es un caso particular.
  Este patrón coincide con todo lo que no ha sido buscado previamente.
  Por ejemplo:
  <informalexample>
   <programlisting role="php">
<![CDATA[
<?php
$expressionResult = match ($condition) {
    1, 2 => foo(),
    3, 4 => bar(),
    default => baz(),
};
?>
]]>
   </programlisting>
  </informalexample>
  <note>
   <simpara>
    El uso de múltiples patrones por defecto provocará un error
   <constant>E_FATAL_ERROR</constant>.
   </simpara>
  </note>
 </para>

 <para>
  Una expresión <literal>match</literal> debe ser exhaustiva. Si la expresión
  no es tratada por ningún brazo de <literal>match</literal>, se lanza un error
 <classname>UnhandledMatchError</classname>.
 </para>

 <example>
 <title>Ejemplo de una expresión match no manejada</title>
  <programlisting role="php">
<![CDATA[
<?php
$condition = 5;

try {
    match ($condition) {
        1, 2 => foo(),
        3, 4 => bar(),
    };
} catch (\UnhandledMatchError $e) {
    var_dump($e);
}
?>
]]>
  </programlisting>
  &example.outputs;
  <screen>
<![CDATA[
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
}
]]>
  </screen>
 </example>

 <sect2>
  <title>Uso de expresiones match para manejar controles de no identidad</title>
  <para>
   Es posible utilizar una expresión <literal>match</literal> para tratar
   los casos condicionales de no identidad utilizando <code>true</code> como expresión sujeto.
  </para>

  <example>
  <title>Uso de una expresión match generalizada para realizar ramificaciones sobre rangos de enteros</title>
   <programlisting role="php">
<![CDATA[
<?php

$age = 23;

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

var_dump($result);
?>
]]>
   </programlisting>
   &example.outputs;
   <screen>
<![CDATA[
string(11) "young adult"
]]>
   </screen>
  </example>

  <example>
  <title>Uso de una expresión match generalizada para realizar ramificaciones sobre el contenido de una cadena de caracteres</title>
   <programlisting role="php">
<![CDATA[
<?php

$text = 'Bienvenidos a nuestra casa';

$result = match (true) {
    str_contains($text, 'Welcome'), str_contains($text, 'Hello') => 'en',
    str_contains($text, 'Bienvenidos'), str_contains($text, 'Hola') => 'es',
    // ...
};

var_dump($result);
?>
]]>
   </programlisting>
   &example.outputs;
   <screen>
<![CDATA[
string(2) "es"
]]>
   </screen>
  </example>
 </sect2>
</sect1>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->