match.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->

<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> ramifica la evaluación basada en una
  comprobación de identidad de un valor.
  De forma similar a una sentencia <literal>switch</literal>, una
  expresión <literal>match</literal> tiene una expresión de sujeto que se
  compara con múltiples alternativas. A diferencia de <literal>switch</literal>,
  se evaluará a un valor muy parecido al de las expresiones ternarias.
  A diferencia de <literal>switch</literal>, la comparación es una comprobación de identidad
  (<code>===</code>) en lugar de una comprobación de igualdad débil (<code>==</code>).
  Las expresiones match están disponibles a partir de PHP 8.0.0.
 </para>

 <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>
 </para>

 <para>
  <example>
   <title>Ejemplo básico de uso de <literal>match</literal></title>
   <programlisting role="php">
 <![CDATA[
 <?php
 $comida = 'pastel';

 $valor_devuelto = match ($comida) {
     'manzana' => 'Esta comida es una manzana',
     'barra' => 'Esta comida es una barra',
     'pastel' => 'Esta comida es un pastel',
 };

 var_dump($valor_devuelto);
 ?>
 ]]>
   </programlisting>
   &example.outputs;
   <screen>
<![CDATA[
string(24) "Esta comida es un pastel"
]]>
   </screen>
  </example>
 </para>

 <para>
  <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 => 'Eres un bebé',
     $age < 10 => 'Eres un niño',
     $age < 18 => 'Eres un adolescente',
     $age >= 18 => 'Eres mayor de edad',
     $age < 40 => 'Eres un adulto joven',
     $age >= 40 => 'Eres un adulto viejo'
 };

 var_dump($output);
 ?>
 ]]>
   </programlisting>
   &example.outputs;
   <screen>
<![CDATA[
string(18) "Eres mayor de edad"
]]>
   </screen>
   <note>
    <simpara>
     El resultado de una expresión <literal>match</literal> no necesita ser utilizado.
    </simpara>
   </note>
   <note>
    <simpara>
     Una expresión <literal>match</literal> <emphasis>debe</emphasis> 
     terminar con un punto y coma <literal>;</literal>.
    </simpara>
   </note>
  </example>
 </para>

 <para>
  La expresión <literal>match</literal> es similar a una
  sentencia <literal>switch</literal> pero tiene algunas diferencias clave:
  
  <itemizedlist>
   <listitem>
    <simpara>
     Un brazo de <literal>match</literal> compara los valores estrictamente (<code>===</code>) en lugar
     de hacerlo de forma suelta como lo hace la sentencia switch.
    </simpara>
   </listitem>
   <listitem>
    <simpara>
     Una expresión <literal>match</literal> retorna un valor.
    </simpara>
   </listitem>
   <listitem>
    <simpara>
     Los brazos de <literal>Match</literal> no pasan a casos posteriores
     como lo hacen las sentencias <literal>switch</literal>.
    </simpara>
   </listitem>
   <listitem>
    <simpara>
     Una expresión <literal>match</literal> debe ser completa.
    </simpara>
   </listitem>
  </itemizedlist>
 </para>

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

 <para>
  Los brazos de la expresión <literal>match</literal> pueden contener varias expresiones
  separadas por una coma.  Se trata de un OR lógico, y es una abreviatura de múltiples
  brazos match con el mismo lado derecho.
 </para>
 <para>
  <informalexample>
   <programlisting role="php">
<![CDATA[
<?php
$result = match ($x) {
    // Este brazo match:
    $a, $b, $c => 5,
    // Es equivalente a estos tres:
    $a => 5,
    $b => 5,
    $c => 5,
};
?>
]]>
   </programlisting>
  </informalexample>
 </para>
 <para>
  Un caso especial es el patrón <literal>default</literal>.
  Este patrón permite hacer coincidir cualquier cosa que no se haya hecho coincidir previamente.
  Por ejemplo:
  <informalexample>
   <programlisting role="php">
<![CDATA[
<?php
$expressionResult = match ($condition) {
    1, 2 => foo(),
    3, 4 => bar(),
    default => baz(),
};
?>
]]>
   </programlisting>
  </informalexample>
  <note>
   <simpara>
    Múltiples patrones default lanzarán un
    error <constant>E_FATAL_ERROR</constant>.
   </simpara>
  </note>
 </para>

 <para>
  Una expresión <literal>match</literal> debe ser completa.  Si la
  expresión del sujeto no es manejada por ningún brazo match
  se lanza un <classname>UnhandledMatchError</classname>.
 </para>

 <example>
  <title>Ejemplo de una expresión match no controlada</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>Usando expresiones match para manejar comprobaciones de no identidad</title>
  <para>
   Es posible utilizar un expresión <literal>match</literal> para manejar
   casos de condicionales de no identidad usando <code>true</code> como expresión
   del sujeto.
  </para>

  <example>
   <title>Uso de expresiones match generalizadas para ramificar en rangos de integers</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 expresiones match generalizadas para ramificar el contenido de strings.</title>
   <programlisting role="php">
<![CDATA[
<?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);
?>
]]>
   </programlisting>
   &example.outputs;
   <screen>
<![CDATA[
string(2) "fr"
]]>
   </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
-->