PHP 8.6.0RC7 available for testing

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:

*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 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:

string(3) "abc"

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

Additional arguments

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

Restrictions

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.

+add a note

User Contributed Notes

There are no user contributed notes for this page.
To Top