A class for handling variadic functions with a variable number of arguments for PHP >= 5.3.
Variadic functions are functions which take a variable number of arguments. As of this RFC, developed by Nikita Popov, this feature will be part of PHP 5.6.
Variadic functions allow you to capture a variable number of arguments to a function, combined with "normal" arguments passed in if you like. It's easiest to see with an example:
<?php
function concatenate($transform, ...$strings) {
$string = '';
foreach ( $strings as $piece ) {
$string .= $piece;
}
return $transform($string);
}
echo concatenate("strtoupper", "I'd ", "like ",
4 + 2, " apples");
?>The parameters list in the function declaration has the ... operator (referred to as either the splat operator or the scatter operator) in it, and it basically means " ... and everything else should go into $strings". You can pass 2 or more arguments into this function and the second and subsequent ones will be added to the $strings array, ready to be used.
Variadic functions are already possible in PHP and have been throughout 4.x and 5.x in the form of func_get_args(), which is pretty gross. It's used for functions where you want to have an unlimited number of functions like the example from above:
<?php
function concatenate($transform) {
$strings = func_get_args();
// Remove $transform from the array of arguments
array_shift($strings);
$strings = reset($strings); // Faffing...
$string = '';
foreach ( $strings as $piece ) {
$string .= $piece;
}
return $transform($string);
}
echo concatenate("strtoupper", "I'd ", "like ",
4 + 2, " apples");
?>This super-trivial example shows off the difference between the two approaches:
- The new variadic syntax would make it strikingly obvious what is happening in the function declaration, which is where arguments come from. Furthermore it makes it a lot easier to write self documenting code.
- See the faffing comment? With the new variadic syntax there is no need for horrendous faffing arounds with
array_shiftand Co.
Now here comes the reason why this project come into life:
Variadic tries to incorporate the new variadic syntax for PHP >= 5.3 and implements a wrapper for variadic functions. Focus was put on easy use and simple integration in other projects.
You have two options for adding Variadic to your project:
- Download the latest release or
- Clone the repository:
git clone git://github.com/sommerregen/variadic.git
The only file required is Variadic.php, so copy that to your include directory.
The typical flow of Variadic is to call the built-in functions call_user_variadic or call_user_variadic_array like the PHP built-in functions call_user_func and call_user_func_array and define a function like:
<?php
require('Variadic.php');
function concatenate($transform, $args) {
$string = '';
foreach ( $args as $piece ) {
$string .= $piece;
}
return $transform($string);
}
echo call_user_variadic('concatenate', "strtoupper", "I'd ",
"like ", 4 + 2, " apples") . "<br>";
// or
echo call_user_variadic_array('concatenate', array("strtoupper",
"I'd ", "like ", 4 + 2, " apples"));
// both result in "I'D LIKE 6 APPLES"
?>Note the subtleties between this syntax and the new variadic syntax: The splat operator was omitted and instead of using $strings as a parameter we use the special variadic argument $args, which will incorporate all nice features from the new syntax.
Variadic comes with other useful extensions. It repopulates the callable objects parameter from an indexed array of arguments, e.g.
<?php
echo call_user_variadic_array('concatenate', array("I'd ",
"like ", 4 + 2, " apples", 'transform' => "strtoupper"));
// result: "I'D LIKE 6 APPLES"
?>As you can see, it doesn't even matter where indexed arguments appear, because all index arguments are delegated to their respective parameters of the function. You can also pass index arguments to call_user_variadic using a special syntax, where the name of the callable object's parameter always comes first, followed by its value (here: the parameter name 'transform' marks the key and "strtoupper" the value). The rest is passed to the $args parameter:
<?php
echo call_user_variadic('concatenate', 'transform', "strtoupper",
'args', array("I'd ", "like ", 4 + 2, " apples"));
// result: "I'D LIKE 6 APPLES"
?>Please note, when changing the head e.g. function concatenate($transform, $args) to function concatenate($transform, $strings), then the above examples won't apply anymore. This is due to the special role of the $args parameter (here referred to as special variadic argument). You can change the special variadic argument name by creating an instance of Variadic and set the property keyword to any name you like, i.e.
<?php
$variadic = new Variadic();
$variadic->keyword = 'strings';
?>You can adjust many more settings. If you want to do so, please read the documentation for a complete guide of usage.
You can contribute at any time! Before opening any issue, please search for existing issues and review the guidelines for contributing.
After that please note:
- If you find a bug or would like to make a feature request or suggest an improvement, please open a new issue. If you have any interesting ideas for additions to the syntax please do suggest them as well!
- Feature requests are more likely to get attention if you include a clearly described use case.
- If you wish to submit a pull request, please make again sure that your request match the guidelines for contributing and that you keep track of adding unit tests for any new or changed functionality.
Feel free to support me at any time. Donations keep this project alive. You can always 
Copyright (c) 2014 Benjamin Regler. See also the list of contributors who participated in this project. Dual-licensed for use under the terms of the MIT license or GPLv3 license (license terms can be also be found in LICENSE).