Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Document named arguments #251

Closed
wants to merge 3 commits into from
Closed

Document named arguments #251

Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
de0f84f
Document named arguments
ekinhbayar Nov 29, 2020
330fce5
Rewording named arguments documentation as per PR review
ekinhbayar Nov 29, 2020
54c4444
Fix build problems caused by the use of null reference in the code block
ekinhbayar Nov 30, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
128 changes: 128 additions & 0 deletions language/functions.xml
View file
Open in desktop
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 arguments of the form
<code>Type $param = &null;</code>, 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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
function based on the parameter name, rather than the parameter position.
function based on the argument name, rather than the argument position.

Again for consistency with the beginning of the paragraph

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this one is a legit use of argument, as it's again talking about the name vs position of the parameter at the function definition.

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
cmb69 marked this conversation as resolved.
Show resolved Hide resolved
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 example as above with a different order of parameters</title>
<programlisting role="php">
<![CDATA[
<?php
array_fill(value: 50, num: 100, start_index: 0);
?>
]]>
</programlisting>
</example>

<para>
Named arguments can be combined 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