|
|
Partial function application
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:
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 placeholders
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:
Evaluation of the arguments
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
Restrictions
-
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 argument
An ArgumentCountError is thrown when the
Closure is created if the number of arguments
and placeholders does not match the parameters of the function.
|