language/functions.xml
b22f4a798a435fb159af88806341ce9cbe9f38c2
...
...
@@ -227,28 +227,6 @@ function takes_many_args(
227
227
]]>
228
228
</programlisting>
229
229
</example>
230
-
<para>
231
-
As of PHP 8.0.0, declaring mandatory arguments after optional arguments
232
-
is deprecated. This can generally be resolved by dropping the default value.
233
-
One exception to this rule are arguments of the form
234
-
<code>Type $param = null</code>, where the &null; default makes the type implicitly
235
-
nullable. This usage remains allowed, though it is recommended to use an
236
-
explicit nullable type instead.
237
-
</para>
238
-
<example>
239
-
<title>Declaring optional arguments after mandatory arguments</title>
240
-
<programlisting role="php">
241
-
<![CDATA[
242
-
<?php
243
-
function foo($a = [], $b) {} // Before
244
-
function foo($a, $b) {} // After
245
-

246
-
function bar(A $a = null, $b) {} // Still allowed
247
-
function bar(?A $a, $b) {} // Recommended
248
-
?>
249
-
]]>
250
-
</programlisting>
251
-
</example>
252
230

253
231
<sect2 xml:id="functions.arguments.by-reference">
254
232
<title>Passing arguments by reference</title>
...
...
@@ -289,8 +267,10 @@ echo $str; // outputs 'This is a string, and something extra.'
289
267
<title>Default argument values</title>
290
268
291
269
<para>
292
-
A function may define C++-style default values for scalar
293
-
arguments as follows:
270
+
A function may define default values for arguments using syntax similar
271
+
to assigning a variable. The default is used only when the parameter is
272
+
not specified; in particular, note that passing &null; does <emphasis>not</emphasis>
273
+
assign the default value.
294
274
</para>
295
275
<para>
296
276
<example>
...
...
@@ -319,8 +299,9 @@ Making a cup of espresso.
319
299
</example>
320
300
</para>
321
301
<para>
322
-
PHP also allows the use of <type>array</type>s and the special type &null;
323
-
as default values, for example:
302
+
Default parameter values may be scalar values, <type>array</type>s,
303
+
the special type &null;, and as of PHP 8.1.0, objects using the
304
+
<link linkend="language.oop5.basic.new">new ClassName()</link> syntax.
324
305
</para>
325
306
<para>
326
307
<example>
...
...
@@ -334,21 +315,46 @@ function makecoffee($types = array("cappuccino"), $coffeeMaker = NULL)
334
315
return "Making a cup of ".join(", ", $types)." with $device.\n";
335
316
}
336
317
echo makecoffee();
337
-
echo makecoffee(array("cappuccino", "lavazza"), "teapot");
318
+
echo makecoffee(array("cappuccino", "lavazza"), "teapot");?>
319
+
]]>
320
+
</programlisting>
321
+
</example>
322
+
</para>
323
+
<para>
324
+
<example>
325
+
<title>Using objects as default values (as of PHP 8.1.0)</title>
326
+
<programlisting role="php">
327
+
<![CDATA[
328
+
<?php
329
+
class DefaultCoffeeMaker {
330
+
public function brew() {
331
+
return 'Making coffee.';
332
+
}
333
+
}
334
+
class FancyCoffeeMaker {
335
+
public function brew() {
336
+
return 'Crafting a beautiful coffee just for you.';
337
+
}
338
+
}
339
+
function makecoffee($coffeeMaker = new DefaultCoffeeMaker)
340
+
{
341
+
return $coffeeMaker->brew();
342
+
}
343
+
echo makecoffee();
344
+
echo makecoffee(new FancyCoffeeMaker);
338
345
?>
339
346
]]>
340
347
</programlisting>
341
348
</example>
342
-
343
349
</para>
344
350
<simpara>
345
351
The default value must be a constant expression, not (for
346
352
example) a variable, a class member or a function call.
347
353
</simpara>
348
354
<para>
349
-
Note that when using default arguments, any defaults should be on
350
-
the right side of any non-default arguments; otherwise, things
351
-
will not work as expected. Consider the following code snippet:
355
+
Note that any optional arguments should be specified after any
356
+
required arguments, otherwise they cannot be omitted from calls.
357
+
Consider the following example:
352
358
</para>
353
359
<para>
354
360
<example>
...
...
@@ -356,21 +362,20 @@ echo makecoffee(array("cappuccino", "lavazza"), "teapot");
356
362
<programlisting role="php">
357
363
<![CDATA[
358
364
<?php
359
-
function makeyogurt($type = "acidophilus", $flavour)
365
+
function makeyogurt($container = "bowl", $flavour)
360
366
{
361
-
return "Making a bowl of $type $flavour.\n";
367
+
return "Making a $container of $flavour yogurt.\n";
362
368
}
363
369
364
-
echo makeyogurt("raspberry"); // won't work as expected
370
+
echo makeyogurt("raspberry"); // "raspberry" is $container, not $flavour
365
371
?>
366
372
]]>
367
373
</programlisting>
368
374
&example.outputs;
369
375
<screen>
370
376
<![CDATA[
371
-
Warning: Missing argument 2 in call to makeyogurt() in
372
-
/usr/local/etc/httpd/htdocs/phptest/functest.html on line 41
373
-
Making a bowl of raspberry .
377
+
Fatal error: Uncaught ArgumentCountError: Too few arguments
378
+
to function makeyogurt(), 1 passed in example.php on line 42
374
379
]]>
375
380
</screen>
376
381
</example>
...
...
@@ -384,23 +389,80 @@ Making a bowl of raspberry .
384
389
<programlisting role="php">
385
390
<![CDATA[
386
391
<?php
387
-
function makeyogurt($flavour, $type = "acidophilus")
392
+
function makeyogurt($flavour, $container = "bowl")
388
393
{
389
-
return "Making a bowl of $type $flavour.\n";
394
+
return "Making a $container of $flavour yogurt.\n";
390
395
}
391
396
392
-
echo makeyogurt("raspberry"); // works as expected
397
+
echo makeyogurt("raspberry"); // "raspberry" is $flavour
393
398
?>
394
399
]]>
395
400
</programlisting>
396
401
&example.outputs;
397
402
<screen>
398
403
<![CDATA[
399
-
Making a bowl of acidophilus raspberry.
404
+
Making a bowl of raspberry yogurt.
400
405
]]>
401
406
</screen>
402
407
</example>
403
408
</para>
409
+
<para>
410
+
As of PHP 8.0.0, <link linkend="functions.named-arguments">named arguments</link>
411
+
can be used to skip over multiple optional parameters.
412
+
</para>
413
+
<para>
414
+
<example>
415
+
<title>Correct usage of default function arguments</title>
416
+
<programlisting role="php">
417
+
<![CDATA[
418
+
<?php
419
+
function makeyogurt($container = "bowl", $flavour = "raspberry", $style = "Greek")
420
+
{
421
+
return "Making a $container of $flavour $style yogurt.\n";
422
+
}
423
+

424
+
echo makeyogurt(style: "natural");
425
+
?>
426
+
]]>
427
+
</programlisting>
428
+
&example.outputs;
429
+
<screen>
430
+
<![CDATA[
431
+
Making a bowl of raspberry natural yogurt.
432
+
]]>
433
+
</screen>
434
+
</example>
435
+
</para>
436
+
<para>
437
+
As of PHP 8.0.0, declaring mandatory arguments after optional arguments
438
+
is <emphasis>deprecated</emphasis>. This can generally be resolved by
439
+
dropping the default value, since it will never be used.
440
+
One exception to this rule are arguments of the form
441
+
<code>Type $param = null</code>, where the &null; default makes the type implicitly
442
+
nullable. This usage remains allowed, though it is recommended to use an
443
+
explicit <link linkend="language.types.declarations.nullable">nullable type</link> instead.
444
+
<example>
445
+
<title>Declaring optional arguments after mandatory arguments</title>
446
+
<programlisting role="php">
447
+
<![CDATA[
448
+
<?php
449
+
function foo($a = [], $b) {} // Default not used; deprecated as of PHP 8.0.0
450
+
function foo($a, $b) {} // Functionally equivalent, no deprecation notice
451
+

452
+
function bar(A $a = null, $b) {} // Still allowed; $a is required but nullable
453
+
function bar(?A $a, $b) {} // Recommended
454
+
?>
455
+
]]>
456
+
</programlisting>
457
+
</example>
458
+
</para>
459
+
<note>
460
+
<simpara>
461
+
As of PHP 7.1.0, omitting a parameter which does not specify a default
462
+
throws an <classname>ArgumentCountError</classname>; in previous versions
463
+
it raised a Warning.
464
+
</simpara>
465
+
</note>
404
466
<note>
405
467
<simpara>
406
468
Arguments that are passed by reference may have a default value.
...
...
@@ -417,22 +479,11 @@ Making a bowl of acidophilus raspberry.
417
479
<literal>...</literal> token.
418
480
</simpara>
419
481

420
-
<note>
421
-
<simpara>
422
-
It is also possible to achieve variable-length arguments by using
423
-
<function>func_num_args</function>,
424
-
<function>func_get_arg</function>, and
425
-
<function>func_get_args</function> functions.
426
-
This technique is not recommended as it was used prior to the introduction
427
-
of the <literal>...</literal> token.
428
-
</simpara>
429
-
</note>
430
-

431
482
<para>
432
483
Argument lists may include the
433
484
<literal>...</literal> token to denote that the function accepts a
434
485
variable number of arguments. The arguments will be passed into the
435
-
given variable as an array; for example:
486
+
given variable as an &array;:
436
487

437
488
<example>
438
489
<title>Using <literal>...</literal> to access variable arguments</title>
...
...
@@ -543,46 +594,6 @@ Catchable fatal error: Argument 2 passed to total_intervals() must be an instanc
543
594
(<literal>&amp;</literal>).
544
595
</para>
545
596

546
-
<sect3 xml:id="functions.variable-arg-list.old">
547
-
<title>Older versions of PHP</title>
548
-

549
-
<para>
550
-
No special syntax is required to note that a function is variadic;
551
-
however access to the function's arguments must use
552
-
<function>func_num_args</function>, <function>func_get_arg</function>
553
-
and <function>func_get_args</function>.
554
-
</para>
555
-

556
-
<para>
557
-
The first example above would be implemented as follows in old versions of PHP:
558
-

559
-
<example>
560
-
<title>Accessing variable arguments in old PHP versions</title>
561
-
<programlisting role="php">
562
-
<![CDATA[
563
-
<?php
564
-
function sum() {
565
-
$acc = 0;
566
-
foreach (func_get_args() as $n) {
567
-
$acc += $n;
568
-
}
569
-
return $acc;
570
-
}
571
-

572
-
echo sum(1, 2, 3, 4);
573
-
?>
574
-
]]>
575
-
</programlisting>
576
-
&example.outputs;
577
-
<screen>
578
-
<![CDATA[
579
-
10
580
-
]]>
581
-
</screen>
582
-
</example>
583
-
</para>
584
-
</sect3>
585
-

586
597
</sect2>
587
598

588
599
<sect2 xml:id="functions.named-arguments">
...
...
@@ -606,7 +617,7 @@ echo sum(1, 2, 3, 4);
606
617
<example>
607
618
<title>Named argument syntax</title>
608
619
<programlisting role="php">
609
-
<![CDATA[
620
+
<![CDATA[
610
621
<?php
611
622
myFunction(paramName: $value);
612
623
array_foobar(array: $value);
...
...
@@ -621,7 +632,7 @@ function_name($variableStoringParamName: $value);
621
632
<example>
622
633
<title>Positional arguments versus named arguments</title>
623
634
<programlisting role="php">
624
-
<![CDATA[
635
+
<![CDATA[
625
636
<?php
626
637
// Using positional arguments:
627
638
array_fill(0, 100, 50);
...
...
@@ -640,7 +651,7 @@ array_fill(start_index: 0, count: 100, value: 50);
640
651
<example>
641
652
<title>Same example as above with a different order of parameters</title>
642
653
<programlisting role="php">
643
-
<![CDATA[
654
+
<![CDATA[
644
655
<?php
645
656
array_fill(value: 50, count: 100, start_index: 0);
646
657
?>
...
...
@@ -658,7 +669,7 @@ array_fill(value: 50, count: 100, start_index: 0);
658
669
<example>
659
670
<title>Combining named arguments with positional arguments</title>
660
671
<programlisting role="php">
661
-
<![CDATA[
672
+
<![CDATA[
662
673
<?php
663
674
htmlspecialchars($string, double_encode: false);
664
675
// Same as
...
...
@@ -673,9 +684,9 @@ htmlspecialchars($string, ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML401, 'UTF-8', fa
673
684
</para>
674
685

675
686
<example>
676
-
<title>Error exception when passing the same parameter multiple times</title>
687
+
<title>Error thrown when passing the same parameter multiple times</title>
677
688
<programlisting role="php">
678
-
<![CDATA[
689
+
<![CDATA[
679
690
<?php
680
691
function foo($param) { ... }
681
692

...
...
@@ -688,6 +699,29 @@ foo(1, param: 2);
688
699
</programlisting>
689
700
</example>
690
701

702
+
<para>
703
+
As of PHP 8.1.0, it is possible to use named arguments after unpacking the arguments.
704
+
A named argument <emphasis>must not</emphasis> override an already unpacked argument.
705
+
</para>
706
+

707
+
<example>
708
+
<title>Use named arguments after unpacking</title>
709
+
<programlisting role="php">
710
+
<![CDATA[
711
+
<?php
712
+
function foo($a, $b, $c = 3, $d = 4) {
713
+
return $a + $b + $c + $d;
714
+
}
715
+

716
+
var_dump(foo(...[1, 2], d: 40)); // 46
717
+
var_dump(foo(...['b' => 2, 'a' => 1], d: 40)); // 46
718
+

719
+
var_dump(foo(...[1, 2], b: 20)); // Fatal error. Named parameter $b overwrites previous argument
720
+
?>
721
+
]]>
722
+
</programlisting>
723
+
</example>
724
+

691
725
</sect2>
692
726
</sect1>
693
727
...
...
@@ -979,6 +1013,38 @@ $func(); // prints "bar"
979
1013
be thrown in this case.
980
1014
</simpara>
981
1015
</note>
1016
+
<note>
1017
+
<para>
1018
+
Scalar types for built-in functions are nullable by default in coercive mode.
1019
+
As of PHP 8.1.0, passing &null; to an internal function parameter that is not declared nullable
1020
+
is discouraged and emits a deprecation notice in coercive mode to align with the behavior of user-defined functions,
1021
+
where scalar types need to be marked as nullable explicitly.
1022
+
</para>
1023
+

1024
+
<para>
1025
+
For example, <function>strlen</function> function expects the parameter <literal>$string</literal>
1026
+
to be a non-nullable &string;.
1027
+
For historical reasons, PHP allows passing &null; for this parameter in coercive mode, and the parameter is
1028
+
implicitly cast to <type>string</type>, resulting in a <literal>""</literal> value.
1029
+
In contrast, a <classname>TypeError</classname> is emitted in strict mode.
1030
+
</para>
1031
+

1032
+
<example>
1033
+
<programlisting role="php">
1034
+
<![CDATA[
1035
+
<?php
1036
+
var_dump(strlen(null));
1037
+
// "Deprecated: Passing null to parameter #1 ($string) of type string is deprecated" as of PHP 8.1.0
1038
+
// int(0)
1039
+

1040
+
var_dump(str_contains("foobar", null));
1041
+
// "Deprecated: Passing null to parameter #2 ($needle) of type string is deprecated" as of PHP 8.1.0
1042
+
// bool(true)
1043
+
?>
1044
+
]]>
1045
+
</programlisting>
1046
+
</example>
1047
+
</note>
982
1048

983
1049
<sect2 role="seealso">
984
1050
&reftitle.seealso;
...
...
@@ -1034,8 +1100,7 @@ echo preg_replace_callback('~-([a-z])~', function ($match) {
1034
1100
<programlisting role="php">
1035
1101
<![CDATA[
1036
1102
<?php
1037
-
$greet = function($name)
1038
-
{
1103
+
$greet = function($name) {
1039
1104
printf("Hello %s\r\n", $name);
1040
1105
};
1041
1106

...
...
@@ -1285,7 +1350,7 @@ NULL
1285
1350
$func = static function() {
1286
1351
// function body
1287
1352
};
1288
-
$func = $func->bindTo(new StdClass);
1353
+
$func = $func->bindTo(new stdClass);
1289
1354
$func();
1290
1355

1291
1356
?>
1292
1357