Partial function application is available as of PHP 8.6.0. A function or method call that provides some of the arguments and uses placeholders for the others does not perform the call. Instead, it creates a Closure whose parameters are the ones that were replaced by a placeholder. It extends the first class callable syntax, which is the particular case where no argument is provided: any expression that can be called may be used, and the function or method to call is determined when the Closure is created.
? stands for exactly one argument. The corresponding
parameter of the Closure is always required,
even if the parameter of the original function is optional.
... stands for all the parameters that have not been
mentioned otherwise. These keep their default values, and a
variadic parameter remains variadic. It may only appear once, and
must be the last argument.
Example #1 Partial function application
<?php
function volume(int $length, int $width, int $height): int
{
return $length * $width * $height;
}
// "?" stands for exactly one argument
$closure = volume(2, ?, 4);
// equivalent to: static fn(int $width): int => volume(2, $width, 4)
var_dump($closure(3));
$closure = volume(?, 3, ?);
// equivalent to: static fn(int $length, int $height): int => volume($length, 3, $height)
var_dump($closure(2, 4));
// "..." stands for all remaining arguments
$closure = volume(2, ...);
// equivalent to: static fn(int $width, int $height): int => volume(2, $width, $height)
var_dump($closure(3, 4));
// With every argument provided, "..." merely delays the call
$closure = volume(2, 3, 4, ...);
// equivalent to: static fn(): int => volume(2, 3, 4)
var_dump($closure());
?>The above example will output:
int(24) int(24) int(24) int(24)
Partial function application is a convenient way of providing the single-parameter callable expected by the pipe operator.
Example #2 Partial function application with |>
<?php
echo ' Hello World '
|> trim(...)
|> str_replace(' ', '', ?)
|> strtoupper(...)
|> str_pad(?, 12, '*', STR_PAD_BOTH);
?>The above example will output:
*HELLOWORLD*
The parameters of the Closure take their name, type declaration and pass-by-reference mode from the original function, as well as its return type. Partial function application can be used in constant expressions, provided that the arguments are constant expressions themselves.
Named arguments may
be used to provide an argument, and a placeholder may be named as
well, using name: ?. As in a regular call, they must come
after the positional arguments. The parameters of the
Closure follow the order in which the named
placeholders are written, which makes it possible to reorder them.
Example #3 Named placeholders
<?php
// The parameters of the closure are $subject, then $search
$remove = str_replace(subject: ?, search: ?, replace: '');
var_dump($remove('a-b-c', '-'));
?>The above example will output:
string(3) "abc"
The provided arguments are evaluated once, when the Closure is created, and not each time it is called. This differs from an arrow function wrapping the same call, whose body is evaluated on every call.
Example #4 Arguments are evaluated when the Closure is created
<?php
function now(): string
{
echo "now() called\n";
return '12:00';
}
function greet(string $name, string $time): string
{
return "Hello $name, it is $time\n";
}
$arrow = fn(string $name) => greet($name, now());
echo "Arrow function created\n";
echo $arrow('Alice');
$partial = greet(?, now());
echo "Partial application created\n";
echo $partial('Bob');
?>The above example will output:
Arrow function created now() called Hello Alice, it is 12:00 now() called Partial application created Hello Bob, it is 12:00
If the ... placeholder is not used, arguments passed to
the Closure beyond its parameters are ignored.
If it is used, they are forwarded to the original function. This
matters when the Closure is used as a callback
by a function passing more arguments than expected, such as the key
of an array element: with ... these reach the optional
parameters of the original function.
Example #5 Additional arguments are only forwarded with ...
<?php
function greet(string $name, string $greeting = 'Hello'): string
{
return "$greeting $name\n";
}
// The second argument is ignored
$closure = greet(?);
echo $closure('Alice', 'Goodbye');
// The second argument is forwarded to greet()
$closure = greet(?, ...);
echo $closure('Alice', 'Goodbye');
?>The above example will output:
Hello Alice Goodbye Alice
Object creation (e.g. new Foo(1, ?)) is not supported,
because new Foo() syntax is not considered a call.
Placeholders cannot be combined with the nullsafe operator.
Placeholders cannot be combined with argument unpacking.
Functions that inspect the calling scope, such as compact(), extract(), func_get_args() and get_defined_vars(), cannot be used. An Error is thrown.
Example #6 Invalid usages resulting in a compile-time error
<?php
new Foo(1, ?); // Cannot create Closure for new expression
$obj?->method(1, ?); // Cannot combine nullsafe operator with Closure creation
foo(?, ...$array); // Cannot combine partial application and unpacking
foo(..., ?); // Variadic placeholder must be last
foo(a: 1, ?); // Cannot use positional argument after named argumentAn ArgumentCountError is thrown when the Closure is created if the number of arguments and placeholders does not match the parameters of the function.