PHP RFC: Syntax for variadic functions

• Date: 2013-08-27
• Author: Nikita Popov nikic@php.net
• Status: Implemented in PHP 5.6 (git:0d7a6388)
• Patch: https://github.com/php/php-src/pull/421
• Mailing list discussion: http://markmail.org/message/uhewgv7zaagkgzdv

Currently variadic functions are implemented by fetching the function arguments using func_get_args(). The following code sample shows an implementation of a variadic function used to prepare and execute a MySQL query (I'll be making use of this example throughout the RFC):

class MySQL implements DB {
    protected $pdo;
    public function query($query) {
        $stmt = $this->pdo->prepare($query);
        $stmt->execute(array_slice(func_get_args(), 1));
        return $stmt;
    }
    // ...
}
 
$userData = $db->query('SELECT * FROM users WHERE id = ?', $userID)->fetch();

There are two issues with the above approach:

Firstly, by just looking at the function signature public function query($query) you cannot know that this is actually a variadic function. You'd think that the function can only run a normal query and doesn't support bound parameters.

Secondly, because func_get_args() returns *all* arguments passed to the function you first need to remove the $query parameter using array_slice(func_get_args(), 1).

This RFC proposed to solve these issues by adding a special syntax for variadic functions:

class MySQL implements DB {
    public function query($query, ...$params) {
        $stmt = $this->pdo->prepare($query);
        $stmt->execute($params);
        return $stmt;
    }
    // ...
}
 
$userData = $db->query('SELECT * FROM users WHERE id = ?', $userID)->fetch();

The ...$params syntax indicates that this is a variadic function and that all arguments after $query should be put into the $params array. Using the new syntax both of the issues mentioned above are solved.

The following example shows how the variadic parameter ...$params is populated depending on the number of passed arguments:

function fn($reqParam, $optParam = null, ...$params) {
    var_dump($reqParam, $optParam, $params);
}
 
fn(1);             // 1, null, []
fn(1, 2);          // 1, 2, []
fn(1, 2, 3);       // 1, 2, [3]
fn(1, 2, 3, 4);    // 1, 2, [3, 4]
fn(1, 2, 3, 4, 5); // 1, 2, [3, 4, 5]

$params will be an empty array if the number of passed arguments is smaller than the number of declared parameters. Any further arguments will be added to the $params array (in the order in which they were passed). The $params array is using continuous zero-based indices.

The new syntax additionally adds support for capturing variadic arguments by-reference, something that was previously not possible in userland code. Only internal functions could make use of this via ZEND_ACC_PASS_REST_BY_REF.

This would allow implementing functions like sscanf() or mysqli_stmt::bind_param() in userland. The following method uses the new syntax to prepare a query and bind parameters by-reference to it:

class MySQL implements DB {
    public function prepare($query, &...$params) {
        $stmt = $this->pdo->prepare($query);
        foreach ($params as $i => &$param) {
            $stmt->bindParam($i + 1, $param);
        }
        return $stmt;
    }
    // ...
}
 
$stmt = $db->prepare('INSERT INTO users (name, email, age) VALUES (?, ?, ?)', $name, $email, $age);
foreach ($usersToInsert as list($name, $email, $age)) {
    $stmt->execute();
}

A by-reference capture of variadic arguments is indicated by a & before the ellipsis ....

Furthermore it's possible to provide a typehint that all variadic arguments are checked against. E.g. this is how the signature of array_merge implemented in userland would look like:

function array_merge(array ...$arrays) { /* ... */ }

PHP would make sure that all arguments are actually arrays. This also works for all other typehints like callable ...$callbacks or Route ...$routes.

An advantage of declaring variadics in the parameter list is that the signature can be enforced by intefaces and during inheritance. The MySQL::query() and MySQL::prepare() examples above already referenced an interface DB. This is how the interface could look like:

interface DB {
    public function query($query, ...$params);
    public function prepare($query, &...$params);
    // ...
}

This interface will force any implementation to make both these functions variadic and will also enforce the by-ref capture for prepare().

The exact protoype checks (what is valid and what is not) are outlined below:

// INVALID: Turning a variadic function into a non-variadic one
public function query($query, ...$params)
public function query($query)
 
// VALID: Turning a non-variadic function into a variadic one
public function query($query)
public function query($query, ...$params)
// Note: This is allowed as ...$params is optional and PHP allows additional optional arguments
 
// INVALID: Changing the passing mode for variadic parameters
public function query($query, &...$params)
public function query($query, ...$params)
 
// INVALID: Changing the typehint of a variadic parameter to an incompatible typehint
public function query($query, array ...$params)
public function query($query, callable ...$params)
 
// INVALID: Removing parameter before the variadic parameter
public function query($query, ...$params)
public function query(...$params)
// Note: Personally I don't think this makes sense, but this is how
//       PHP behaves in general, so I'm staying consistent with it
 
// VALID: Adding additional optional parameter before the variadic parameter (with compatible typehint)
public function query($query, array ...$params)
public function query($query, array $extraParam = null, array ...$params)
 
// INVALID: Adding additional optional parameter with incompatible typehint
public function query($query, array ...$params)
public function query($query, callable $extraParam = null, array ...$params)

There may be only one variadic parameter and it needs to be the last parameter of the function. A variadic parameter may not have a default value.

As such all of the following are invalid:

function fn(...$args, $arg)
function fn(...$args1, ...$args2)
function fn($arg, ...$args = [])

Two new methods are added to Reflection:

bool ReflectionFunction::isVariadic()
bool ReflectionParameter::isVariadic()

The functions will return true if the function/parameter is variadic, false otherwise.

To sum up, the feature adds the following new syntax:

• function fn($arg, ...$args): Capture all variadic arguments into the $args array
• function fn($arg, &...$args): Do the capture by reference
• function fn($arg, array ...$args): Enforce that all variadic arguments are arrays (or some other typehint)
• function fn($arg, array &...$args): Combine both - variadic arguments are arrays that are captured by-reference

The advantages of the syntax are:

• It's immidiately clear that a function is variadic, without having to read documentation.
• It is no longer necessary to array_slice() the variadic arguments from func_get_args()
• It is now possible to do variadic by-reference captures
• Types can be checked with a typehint (rather than a manual loop)
• Variadic prototypes can be enforce in interfaces / by inheritance

This change does not break backwards compatibility for userland code.

In particular, this RFC does not propose to deprecate or remove the func_get_args() family of functions, at least not any time soon.

The pass_rest_by_ref argument of ZEND_BEGIN_ARG_INFO and ZEND_BEING_ARG_INFO_EX is no longer used. Instead functions can declare a variadic argument in the arginfo using ZEND_ARG_VARIADIC_INFO.

For example, this is how the arginfo for sscanf() changed:

// OLD:
ZEND_BEGIN_ARG_INFO_EX(arginfo_sscanf, 1, 0, 2)
    ZEND_ARG_INFO(0, str)
    ZEND_ARG_INFO(0, format)
    ZEND_ARG_INFO(1, ...)
ZEND_END_ARG_INFO()
 
// NEW:
ZEND_BEGIN_ARG_INFO_EX(arginfo_sscanf, 0, 0, 2)
    ZEND_ARG_INFO(0, str)
    ZEND_ARG_INFO(0, format)
    ZEND_ARG_VARIADIC_INFO(1, vars)
ZEND_END_ARG_INFO()

It would theoretically be possible to retain support for pass_rest_by_ref (by automatically generating a variadic arg), but as this is an exceedingly rarely used feature I don't think this is necessary. All usages of it in php-src have been replaced.

Apart from this the change should be transparent from an internals point of view. Macros like ARG_MUST_BE_SENT_BY_REF continue to work.

Presumably this RFC will quickly deteriorate towards a bike-shedding of the best syntax for variadic parameters, so I'll try to explain my choice for the proposed syntax right away:

The use of ... is already familiar from the PHP documentation, where variadics are denoted using a trailing $... parameter. The reason ... follows *before* the parameter in the proposed syntax is to clearly show that the typehint/ref-modifier before it applies to all arguments.

Some possible alternative syntax and why I don't like it:

• $args.... With ref-modifier (&$args...) this does not show well that the individual arguments are references, rather than $args itself. With typehint (array $args...) it also looks like the typehint applies to $args itself rather than all variadic arguments.
• *$args. This is the syntax that both Ruby and Python use. For PHP this does not work well because *$ is a weird combination. It gets worse with a by-reference capture: &*$args. This looks like a random sequences of special characters. Combined with a typehint the syntax looks a lot like a pointer: Foo *$args.
• params $args. This is what C# does. This would require making params a keyword. Furthermore this doesn't have any nice way to declare typehints. In C# this is done using params type[] args, but PHP doesn't have type[] hints and introducing them only here doesn't seem right.

The proposed syntax is also used by Java and will be used in Javascript (ECMAScript Harmony proposal). Go and C++ also employ a similar syntax.

Patch available in PR#421: https://github.com/php/php-src/pull/421

The vote started on 16.09.2013 and ended on 23.09.2013. There were 36 votes in favor and one against, as such the necessary two-third majority is met and this feature is accepted.

Should the proposed variadic-function syntax be added in PHP 5.6 (master)?
Real name	Yes	No
auroraeosrose (auroraeosrose)
blanchonvincent (blanchonvincent)
bukka (bukka)
colder (colder)
datibbaw (datibbaw)
derick (derick)
dmitry (dmitry)
drak (drak)
Fabien Potencier (fabpot)
hradtke (hradtke)
indeyets (indeyets)
jpauli (jpauli)
jwage (jwage)
kalle (kalle)
kassner (kassner)
klaussilveira (klaussilveira)
krakjoe (krakjoe)
leszek (leszek)
levim (levim)
mike (mike)
nikic (nikic)
pajoye (pajoye)
peehaa (peehaa)
pollita (pollita)
rasmus (rasmus)
rdohms (rdohms)
reeze (reeze)
remi (remi)
sean (sean)
seld (seld)
stas (stas)
toby (toby)
treffynnon (treffynnon)
weierophinney (weierophinney)
wez (wez)
yohgaki (yohgaki)
zeev (zeev)
Final result:	36	1
This poll has been closed.

The argument unpacking RFC introduces the following related syntax:

$db->query($query, ...$params);