From de0f84fff5753f915f5ce1acf5166cb1e8a69269 Mon Sep 17 00:00:00 2001
From: ekinhbayar <ekinhbayar@users.noreply.github.com>
Date: Sun, 29 Nov 2020 18:59:16 +0300
Subject: [PATCH] Document named arguments

Also documents deprecation of optional args after mandatory ones
---
 language/functions.xml | 128 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 128 insertions(+)

diff --git a/language/functions.xml b/language/functions.xml
index 6bc703776d01..e1915ba86f17 100644
--- a/language/functions.xml
+++ b/language/functions.xml
@@ -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>
  
@@ -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">