Style improvements, and a couple of extra notes.

This commit is contained in:
Rowan Tommins 2021-12-10 13:50:57 +00:00
parent e6c83ba87a
commit ad1fd84dfa
2 changed files with 45 additions and 42 deletions

View file

@ -63,8 +63,10 @@ var_dump(B::counter()); // int(4), previously int(2)
specified before required parameters is now always treated as required,
even when called using
<link linkend="functions.named-arguments">named arguments</link>.
In PHP 8.0, the below emits a deprecation notice on the definition,
but runs successfully when called. As of PHP 8.1, an error is thrown.
As of PHP 8.0.0, but prior to PHP 8.1.0, the below emits a deprecation notice
on the definition, but runs successfully when called. As of PHP 8.1.0, an error
of class <classname>ArgumentCountError</classname> is thrown, as it would be when
called with positional arguments.
<informalexample>
<programlisting role="php">
@ -87,7 +89,7 @@ catch (Error $e)
</programlisting>
&example.outputs.80;
<screen>
<![CDATA[
<![CDATA[
Deprecated: Required parameter $flavour follows optional parameter $container
in example.php on line 3
Making a bowl of raspberry yogurt.
@ -102,7 +104,11 @@ ArgumentCountError - makeyogurt(): Argument #1 ($container) not passed
]]>
</screen>
</informalexample>
</para>
<para>
Note that a default value of &null; can be used before required parameters to
specify a <link linkend="language.types.declarations.nullable">nullable type</link>,
but the parameter will still be required.
</para>
</sect3>

View file

@ -224,28 +224,6 @@ function takes_many_args(
// ...
}
?>
]]>
</programlisting>
</example>
<para>
As of PHP 8.0.0, declaring mandatory arguments after optional 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>Declaring 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>
@ -291,7 +269,8 @@ echo $str; // outputs 'This is a string, and something extra.'
<para>
A function may define default values for arguments using syntax similar
to assigning a variable. The default is used only when the parameter is
not specified.
not specified; in particular, note that passing &null; does <emphasis>not</emphasis>
assign the default value.
</para>
<para>
<example>
@ -321,7 +300,7 @@ Making a cup of espresso.
</para>
<para>
Default parameter values may be scalar values, <type>array</type>s,
the special type &null;, and as of PHP 8.1, objects using the
the special type &null;, and as of PHP 8.1.0, objects using the
<link linkend="language.oop5.basic.new">new ClassName()</link> syntax.
</para>
<para>
@ -343,7 +322,7 @@ echo makecoffee(array("cappuccino", "lavazza"), "teapot");?>
</para>
<para>
<example>
<title>Using objects as default values (as of PHP 8.1)</title>
<title>Using objects as default values (as of PHP 8.1.0)</title>
<programlisting role="php">
<![CDATA[
<?php
@ -428,7 +407,7 @@ Making a bowl of raspberry yogurt.
</example>
</para>
<para>
As of PHP 8.0, <link linkend="functions.named-arguments">named arguments</link>
As of PHP 8.0.0, <link linkend="functions.named-arguments">named arguments</link>
can be used to skip over multiple optional parameters.
</para>
<para>
@ -454,17 +433,35 @@ Making a bowl of raspberry natural yogurt.
</screen>
</example>
</para>
<para>
As of PHP 8.0.0, declaring mandatory arguments after optional arguments
is <emphasis>deprecated</emphasis>. This can generally be resolved by
dropping the default value, since it will never be used.
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 <link linkend="language.types.declarations.nullable">nullable type</link> instead.
<example>
<title>Declaring optional arguments after mandatory arguments</title>
<programlisting role="php">
<![CDATA[
<?php
function foo($a = [], $b) {} // Default not used; deprecated as of PHP 8.0.0
function foo($a, $b) {} // Functionally equivalent, no deprecation notice
function bar(A $a = null, $b) {} // Still allowed; $a is required but nullable
function bar(?A $a, $b) {} // Recommended
?>
]]>
</programlisting>
</example>
</para>
<note>
<simpara>
As of PHP 7.1, omitting a parameter which does not specify a default
As of PHP 7.1.0, omitting a parameter which does not specify a default
throws an <classname>ArgumentCountError</classname>; in previous versions
it raised a Warning.
</simpara>
<simpara>
As of PHP 8.0, <emphasis>defining</emphasis> a function with optional
parameters after required parameters (as in the first "yogurt"
example above) is DEPRECATED.
</simpara>
</note>
<note>
<simpara>
@ -671,7 +668,7 @@ echo sum(1, 2, 3, 4);
<example>
<title>Named argument syntax</title>
<programlisting role="php">
<![CDATA[
<![CDATA[
<?php
myFunction(paramName: $value);
array_foobar(array: $value);
@ -686,7 +683,7 @@ function_name($variableStoringParamName: $value);
<example>
<title>Positional arguments versus named arguments</title>
<programlisting role="php">
<![CDATA[
<![CDATA[
<?php
// Using positional arguments:
array_fill(0, 100, 50);
@ -705,7 +702,7 @@ array_fill(start_index: 0, count: 100, value: 50);
<example>
<title>Same example as above with a different order of parameters</title>
<programlisting role="php">
<![CDATA[
<![CDATA[
<?php
array_fill(value: 50, count: 100, start_index: 0);
?>
@ -723,7 +720,7 @@ array_fill(value: 50, count: 100, start_index: 0);
<example>
<title>Combining named arguments with positional arguments</title>
<programlisting role="php">
<![CDATA[
<![CDATA[
<?php
htmlspecialchars($string, double_encode: false);
// Same as
@ -738,9 +735,9 @@ htmlspecialchars($string, ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML401, 'UTF-8', fa
</para>
<example>
<title>Error exception when passing the same parameter multiple times</title>
<title>Error thrown when passing the same parameter multiple times</title>
<programlisting role="php">
<![CDATA[
<![CDATA[
<?php
function foo($param) { ... }