====== PHP RFC: Allow a trailing comma in function calls ======
  * Version: 0.1
  * Date: 2017-10-07
  * Author: Sammy Kaye Powers, me@sammyk.me
  * Status: Implemented (in PHP 7.3)
  * First Published at: https://wiki.php.net/rfc/list-syntax-trailing-commas (2017-01-27) & https://wiki.php.net/rfc/trailing-comma-function-args (2013-02-19)

===== Introduction =====
Allowing a trailing comma in function calls will make it more convenient to append arguments in many contexts where it is common to call a function with lots of arguments; especially variadic functions.

===== Proposal =====
A trailing comma has been allowed in array syntax since forever-ever, and in grouped namespace syntax since PHP 7.2.

<code php>
# Currently possible
use Foo\Bar\{
    Foo,
    Bar,
};

$foo = [
    'foo',
    'bar',
];
</code>

Allowing a trailing comma makes sense in these contexts as new values get appended frequently. There is another context wherein appending more values frequently happens: calling a variadic function.

<code php>
unset(
    $foo,
    $bar,
    $baz,
);
</code>

===== Frequent Context Examples =====
A trailing comma in function calls make it crazy convient to invoke any function that takes variable arguments (i.e. using the splat operator <php>...</php> or <php>func_get_args()</php>.)

==== Unsetting variables ====
It is extremely common to send a list of two or more arguments to <php>unset()</php> to unset variables.

<code php>
unset(
    $somethingIDontNeedAnymore,
    $anotherOneToKill,
    $letsMakeThisEasy,
);
</code>

==== Sending variables to a template engine ====
Another extremely common practice is to send a list of variables to a template engine concisely using <php>compact()</php>.

<code php>
echo $twig->render(
    'index.html',
    compact(
        'title',
        'body',
        'comments',
    )
);
</code>

==== Merging arrays ====
Invoking <php>array_merge()</php> is another great example of how a trailing comma makes values easier to append.

<code php>
$newArray = array_merge(
    $arrayOne,
    $arrayTwo,
    ['foo', 'bar'],
);
</code>

==== Debugging all the things ====
When you're quickly debugging with <php>var_dump()</php>, it's nice to not have to worry about removing that dangling comma in order for your script to run.

<code php>
var_dump(
    $whatIsInThere,
    $probablyABugInThisOne,
    $oneMoreToCheck,
);
</code>

==== i18n & l10n ====
Internationalization & localization often makes use of variadic functions such as <php>sprintf()</php> that usually expand and contract over time.

<code php>
$en = 'A trailing %s makes %s a happy developer.';
$text = sprintf(
    $en,
    'comma',
    'Jane',
);
</code>

==== And so on... ====
This list of examples is not meant to be exhaustive, but you can see how allowing a trailing comma in function calls fits well within the existing trailing comma contexts (arrays & grouped namespaces).

===== Method & closure calls too =====
Method calls also adopt trailing comma functionality.

<code php>
class Foo
{
  public function __construct(...$args) {
    //
  }
  
  public function bar(...$args) {
    //
  }
  
  public function __invoke(...$args) {
    //
  }
}

$foo = new Foo(
  'constructor',
  'bar',
);

$foo->bar(
  'method',
  'bar',
);

$foo(
  'invoke',
  'bar',
);
</code>

And closures too.

<code php>
$bar = function(...$args) {
  //
};

$bar(
  'closure',
  'bar',
);
</code>

===== "Not really a function" functions as well =====
There are two language constructs that look like functions but aren't that will also allow a trailing comma: <php>unset()</php> (as mentioned before) and <php>isset()</php>.

<code php>
unset($foo, $bar,);
var_dump(isset($foo, $bar,));
</code>

===== Wait, didn't we just vote on this? =====
Yes, there was an RFC to [[https://wiki.php.net/rfc/list-syntax-trailing-commas|add trailing commas to all list syntax in PHP 7.2]]. Unfortunately due to an oversight on my end, the vote for function calls and function declarations was combined into one vote so the vote failed (but just barely!)

I was contacted by many "no" voters saying that they would have voted "yes" for function calls, but "no" for function declarations. This RFC proposes allowing a trailing comma in function call syntax only.

We are allowed to put this feature up for vote again since the mandatory 6-month waiting period has passed since the last vote and this RFC targets a new major version of PHP.

===== Backward Incompatible Changes =====
None

===== Proposed PHP Version(s) =====
PHP 7.3

===== What's not allowed =====
Function declaration syntax will not change. This RFC targets function call syntax only.

<code php>
# Parse error
function bar($a, $b,) {
    //
}
</code>

Free-standing commas are not allowed.

<code php>
# Parse error
foo(,);
</code>

Multiple trailing commas & leading commas are not allowed.

<code php>
# Parse error
foo('function', 'bar',,);
# Also parse error
foo(, 'function', 'bar');
</code>

Other things that could look like functions like <php>yield</php> & <php>list()</php> will go untouched and no other list syntax will be affected.

===== Proposed Voting Choices =====
Requires a 2/3 majority to pass. Voting begins **2017-10-21 18:30 UTC** and ends **2017-11-04 18:30 UTC**.

<doodle title="Allow a trailing comma in function calls" auth="sammyk" voteType="single" closed="true">
   * Yes
   * No
</doodle>

===== Patches and Tests =====
This patch, sans the tests, is a trivial three-line change in the parser.

[[https://github.com/SammyK/php-src/compare/master...rfc-trailing-comma-function-calls|See the diff on GitHub]]

The trailing comma is thrown out at the parser level so there's no runtime computations wasted.

===== Implementation =====

Implemented in PHP 7.3 via https://github.com/php/php-src/commit/b591c329ee3129adbdc35141bb1542d119f7a2a1.