mirror of
https://github.com/sigmasternchen/php-doc-en
synced 2025-03-15 08:28:54 +00:00
303 lines
6.9 KiB
XML
303 lines
6.9 KiB
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>
|
|
The <literal>match</literal> expression branches evaluation based on an
|
|
identity check of a value.
|
|
Similarly to a <literal>switch</literal> statement, a
|
|
<literal>match</literal> expression has a subject expression that is
|
|
compared against multiple alternatives. Unlike <literal>switch</literal>,
|
|
it will evaluate to a value much like ternary expressions.
|
|
Unlike <literal>switch</literal>, the comparison is an identity check
|
|
(<code>===</code>) rather than a weak equality check (<code>==</code>).
|
|
Match expressions are available as of PHP 8.0.0.
|
|
</para>
|
|
|
|
<example>
|
|
<title>Structure of a <literal>match</literal> expression</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>Basic <literal>match</literal> usage</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>
|
|
|
|
<note>
|
|
<simpara>
|
|
The result of a <literal>match</literal> expression does not need to be used.
|
|
</simpara>
|
|
</note>
|
|
<note>
|
|
<simpara>
|
|
A <literal>match</literal> expression <emphasis>must</emphasis> be
|
|
terminated by a semicolon <literal>;</literal>.
|
|
</simpara>
|
|
</note>
|
|
</example>
|
|
|
|
<para>
|
|
The <literal>match</literal> expression is similar to a
|
|
<literal>switch</literal> statement but has some key differences:
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<simpara>
|
|
A <literal>match</literal> arm compares values strictly (<code>===</code>) instead
|
|
of loosely as the switch statement does.
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
A <literal>match</literal> expression returns a value.
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
<literal>match</literal> arms do not fall-through to later cases the way
|
|
<literal>switch</literal> statements do.
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
A <literal>match</literal> expression must be exhaustive.
|
|
</simpara>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
|
|
<para>
|
|
As <literal>switch</literal> statements, <literal>match</literal>
|
|
expressions are executed match arm by match arm.
|
|
In the beginning, no code is executed.
|
|
The conditional expressions are only evaluated if all previous conditional
|
|
expressions failed to match the subject expression.
|
|
Only the return expression corresponding to the matching conditional
|
|
expression will be evaluated.
|
|
For example:
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
$result = match ($x) {
|
|
foo() => ...,
|
|
$this->bar() => ..., // $this->bar() isn't called if foo() === $x
|
|
$this->baz => beep(), // beep() isn't called unless $x === $this->baz
|
|
// etc.
|
|
};
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</informalexample>
|
|
</para>
|
|
|
|
<para>
|
|
<literal>match</literal> expression arms may contain multiple expressions
|
|
separated by a comma. That is a logical OR, and is a short-hand for multiple
|
|
match arms with the same right-hand side.
|
|
</para>
|
|
<para>
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
$result = match ($x) {
|
|
// This match arm:
|
|
$a, $b, $c => 5,
|
|
// Is equivalent to these three match arms:
|
|
$a => 5,
|
|
$b => 5,
|
|
$c => 5,
|
|
};
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</informalexample>
|
|
</para>
|
|
<para>
|
|
A special case is the <literal>default</literal> pattern.
|
|
This pattern matches anything that wasn't previously matched.
|
|
For example:
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
$expressionResult = match ($condition) {
|
|
1, 2 => foo(),
|
|
3, 4 => bar(),
|
|
default => baz(),
|
|
};
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</informalexample>
|
|
<note>
|
|
<simpara>
|
|
Multiple default patterns will raise a
|
|
<constant>E_FATAL_ERROR</constant> error.
|
|
</simpara>
|
|
</note>
|
|
</para>
|
|
|
|
<para>
|
|
A <literal>match</literal> expression must be exhaustive. If the
|
|
subject expression is not handled by any match arm an
|
|
<classname>UnhandledMatchError</classname> is thrown.
|
|
</para>
|
|
|
|
<example>
|
|
<title>Example of an unhandled match expression</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>Using match expressions to handle non identity checks</title>
|
|
<para>
|
|
It is possible to use a <literal>match</literal> expression to handle
|
|
non-identity conditional cases by using <code>true</code> as the subject
|
|
expression.
|
|
</para>
|
|
|
|
<example>
|
|
<title>Using a generalized match expressions to branch on integer ranges</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>Using a generalized match expressions to branch on string content</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
|
|
-->
|