Skip to content

Commit

Permalink
Document named arguments
Browse files Browse the repository at this point in the history
Also documents deprecation of optional args after mandatory ones
  • Loading branch information
ekinhbayar committed Nov 29, 2020
1 parent ac84f2b commit de0f84f
Showing 1 changed file with 128 additions and 0 deletions.
128 changes: 128 additions & 0 deletions language/functions.xml
Original file line number Diff line number Diff line change
Expand Up @@ -225,6 +225,29 @@ function takes_many_args(
]]>
</programlisting>
</example>
<para>
As of PHP 8.0.0, passing optional arguments after mandatory arguments
is deprecated. This can generally be resolved by dropping the default value.
One exception to this rule are parameters of the form
Type $param = &null;, where the &null; default makes the type implicitly
nullable. This usage remains allowed, though it is recommended to use an
explicit nullable type instead.
</para>
<example>
<title>Passing optional arguments after mandatory arguments</title>
<programlisting role="php">
<![CDATA[
<?php
function foo($a = [], $b) {} // Before
function foo($a, $b) {} // After
function bar(A $a = null, $b) {} // Still allowed
function bar(?A $a, $b) {} // Recommended
?>
]]>
</programlisting>
</example>

<sect2 xml:id="functions.arguments.by-reference">
<title>Passing arguments by reference</title>

Expand Down Expand Up @@ -556,6 +579,111 @@ echo sum(1, 2, 3, 4);
</sect3>

</sect2>

<sect2 xml:id="functions.named-arguments">
<title>Named Arguments</title>

<para>
PHP 8.0.0 introduced named arguments as an extension of the existing
positional parameters. Named arguments allow passing arguments to a
function based on the parameter name, rather than the parameter position.
This makes the meaning of the argument self-documenting, makes the
arguments order-independent and allows skipping default values arbitrarily.
</para>

<para>
Named arguments are passed by prefixing the value with the parameter name
followed by a colon. Using reserved keywords as parameter names is allowed.
The parameter name must be an identifier, specifying dynamically
is not allowed.
</para>

<example>
<title>Named argument syntax</title>
<programlisting role="php">
<![CDATA[
<?php
myFunction(paramName: $value);
array_foobar(array: $value);
// NOT supported.
function_name($variableStoringParamName: $value);
?>
]]>
</programlisting>
</example>

<example>
<title>Positional arguments versus named arguments</title>
<programlisting role="php">
<![CDATA[
<?php
// Using positional arguments:
array_fill(0, 100, 50);
// Using named arguments:
array_fill(start_index: 0, num: 100, value: 50);
?>
]]>
</programlisting>
</example>

<para>
The order in which the named arguments are passed does not matter.
</para>

<example>
<title>Same as above example with a different order of parameters</title>
<programlisting role="php">
<![CDATA[
<?php
array_fill(value: 50, num: 100, start_index: 0);
?>
]]>
</programlisting>
</example>

<para>
You can combine named arguments with positional arguments. In this case,
the named arguments must come after the positional arguments.
It is also possible to specify only some of the optional arguments of a
function, regardless of their order.
</para>

<example>
<title>Combining named arguments with positional arguments</title>
<programlisting role="php">
<![CDATA[
<?php
htmlspecialchars($string, double_encode: false);
// Same as
htmlspecialchars($string, ENT_COMPAT | ENT_HTML401, 'UTF-8', false);
?>
]]>
</programlisting>
</example>

<para>
Passing the same parameter multiple times results in an Error exception.
</para>

<example>
<title>Error exception when passing the same parameter multiple times</title>
<programlisting role="php">
<![CDATA[
<?php
function foo($param) { ... }
foo(param: 1, param: 2);
// Error: Named parameter $param overwrites previous argument
foo(1, param: 2);
// Error: Named parameter $param overwrites previous argument
?>
]]>
</programlisting>
</example>

</sect2>
</sect1>

<sect1 xml:id="functions.returning-values">
Expand Down

0 comments on commit de0f84f

Please sign in to comment.