Skip to content

Partial function application signatures and first-class callable call replay - #7033

Merged
ondrejmirtes merged 20 commits into
2.3.xfrom
pfa-signatures
Nov 15, 2026
Merged

ondrejmirtes merged 20 commits into
2.3.xfrom
pfa-signatures

Conversation

@ondrejmirtes

Copy link
Copy Markdown
Member

Follow-up to #7029: PHP 8.6 partial function application (PFA) closures now get their real signature, and their creation and calls are checked against the PHP 8.6 runtime rules. This also fixes more first-class callable (FCC) problems found along the way. Each commit is self-contained, has its own test, and updates its turbo-ext C++ mirror where needed.

PFA signatures and errors

  • The closure signature follows the PHP 8.6 rules, checked against PHP 8.6 RC3:
    • ? is always required, and named placeholders come in the order they are written.
    • ... pulls in the unbound parameters, keeping their defaults.
    • A ? that lands in a variadic parameter becomes $rest0, $rest1….
    • A function or static method PFA is a static closure.
    • Variants that would throw at creation are dropped.
  • Templates the bound arguments determine are resolved: repeat('a', ?) gives Closure(int): list<'a'>.
  • Creating a closure from arguments that don't fit the callee is reported with the same messages as calls. Placeholder placements PHP refuses to compile are reported even when the callee is unknown.
  • In a variadic closure, a named argument for a parameter the PFA already bound is reported.
  • A function that calls func_get_args() keeps its PFA with ... variadic.
  • A magic method's PFA names its parameters $arguments0… after the __call() trampoline.

Calls of FCC and PFA closures

  • A closure created from a callable records its origin. Calling it replays the call on the callee, so dynamic return types, type-specifying and parameter-out extensions, by-ref effects and throw points apply to stored FCCs and PFAs as they do to direct calls: $r = str_replace(...), $d->modify(...), $sort = sort(...), $pm = preg_match(...), $ake = array_key_exists(...), $j = json_decode(...).
  • An FCC of a multi-variant callee such as max(...) is accepted as a callback when any of its variants fits, as the string 'max' already was.

Closures

  • Closure::__invoke() uses the signature of the closure it is called on. Before, $c->__invoke(1) returned mixed. call-methods.php:139 now reports the same arity error that $closure(1, 2, 3) already got.
  • Unbinding the closure of an instance method gives null. Binding an object to the closure of a static method or to a function's PFA gives null, because both are now static-Closure. A function's FCC stays bindable, as in PHP.

Tests

  • FCC behaviour the suite did not cover: named and by-ref arguments, callbacks to usort/array_reduce/array_walk/call_user_func_array, multi-variant built-ins, @method static, constant expressions, parent::abstract(...), and a result-cache e2e test.
  • The php-src PFA tests (php/php-src@5472cac, php/php-src@b5fba85) were run on PHP 8.6 and through PHPStan. Of the 221 PFA sites that run, 202 give the same closure at runtime and in PHPStan. The other 19 cannot be typed: eval(), untyped code, or magic methods without @method.

Closes phpstan/phpstan#15364

@ondrejmirtes
ondrejmirtes force-pushed the pfa-signatures branch 3 times, most recently from 48697ab to 79a2388 Compare November 13, 2026 14:09
PartialFunctionApplicationParameters maps the callee's parameters to the
closure's following PHP 8.6: positional placeholders, then named ones in
the order written, then what ... adds; a ? is required, ... keeps
optionality and the variadic; a ? past the declared parameters of a
variadic callee is named after the variadic ($rest0, $rest1, ...).
createFirstClassCallable() applies it to every variant and drops the
variants whose partial application throws when created; when none is
left, the closure stays a plain Closure. The native twins call the same
PHP helper, which runs only for partial applications.

Amp-Thread-ID: https://ampcode.com/threads/T-01a1c541-317f-7386-a2ed-9cbd66178685
FunctionCallableNode, MethodCallableNode and StaticMethodCallableNode gain
getArgs() with the bound arguments and placeholders. Their rules pick the
variant the placeholders fit and run FunctionCallParametersCheck through
the new checkPartialApplication(), which resolves templates from the bound
arguments only. The check now reads placeholders: a ? fills a parameter
without a value to check, ... lifts the too-few and missing-parameter
checks, too many arguments are reported regardless of checkExtraArguments
because the creation throws, and the creation-time errors of PHP 8.6 are
reported: a named placeholder for an unknown or variadic parameter,
unpacking, and ... before another argument.

The self-analysis stub of CallLike now includes ArgPlaceholder.

Amp-Thread-ID: https://ampcode.com/threads/T-01a1c541-317f-7386-a2ed-9cbd66178685
PHP 8.6 creates compact(...), extract(...) and the other functions that
cannot be called dynamically as first-class callables and throws only
when they are called; a partial application of them already throws when
it is created.

Amp-Thread-ID: https://ampcode.com/threads/T-01a1c541-317f-7386-a2ed-9cbd66178685
PartialFunctionApplicationParameters::apply() infers template types from
the types of the bound arguments. In the closure's return type, a template
no closure parameter mentions becomes the inferred type and is dropped
from the closure's templates; one a closure parameter still mentions is
unioned with it, as a call would. So repeat('a', ?) is
Closure(int): list<'a'> and pair(?, 'x') is Closure<T>(T): list<'x'|T>.
The handlers pass the bound argument types from the scope, constant
expressions resolve them with the initializer resolver, and the native
twins pass them through the same PHP helper.

Amp-Thread-ID: https://ampcode.com/threads/T-01a1c541-317f-7386-a2ed-9cbd66178685
Incompatible partial applications passed to array_map(), array_filter(),
usort() and a userland generic callable parameter are reported, the
compatible ones, generic ones included, are not, and the templates they
carry flow into the result of userland generic callables.

Amp-Thread-ID: https://ampcode.com/threads/T-01a1c541-317f-7386-a2ed-9cbd66178685
A first-class callable or a partial function application now remembers its
callee (ClosureOrigin): the function, or the method and the type it is called
on, and the arguments a partial application bound. Calling such a closure
replays the call as the callee's call, so the callee's dynamic return type
extensions, type-specifying extensions, by-ref effects and parameter out
types apply as if it had been called directly.

A union of such closures replays each callee: the call returns what any of
them returns, narrows only what all of them narrow and has the effects of
any of them. A member without an origin keeps the call on the closure
signature. Closures with different origins are not equal and are not
subtypes of each other, so a union keeps each origin.

Amp-Thread-ID: https://ampcode.com/threads/T-01a1c541-317f-7386-a2ed-9cbd66178685
PHP throws "Named parameter $x overwrites previous argument" when a variadic
closure created by a partial function application is called with a named
argument for a parameter the application already bound, positionally or by
name. The origin of the closure now carries the names of the bound
parameters, and calling the closure with one of them is reported.

Amp-Thread-ID: https://ampcode.com/threads/T-01a1c541-317f-7386-a2ed-9cbd66178685
A closure created from a callable carries the throw points of any call of
its callee, so a stored json_decode(...) called without JSON_THROW_ON_ERROR
still claimed to throw JsonException, and with implicit throws off a stored
strlen(...) claimed to throw. The replayed call of the callee already knows
the throw points of this call; the closure call now uses them.

Amp-Thread-ID: https://ampcode.com/threads/T-01a1c541-317f-7386-a2ed-9cbd66178685
- named and by-ref arguments of a stored first-class callable
- usort(), uasort(), array_reduce(), array_walk() and call_user_func_array()
  with first-class callable callbacks, compatible and not
- the closure types of multi-variant built-ins and of @method static
- templates kept through a first-class callable of a first-class callable
- the type of new Foo(...)
- first-class callables in constant expressions (PHP 8.5), called
- parent::abstractMethod(...)
- result cache dependencies of the target of a first-class callable

Amp-Thread-ID: https://ampcode.com/threads/T-01a1c541-317f-7386-a2ed-9cbd66178685
…ant fits

A first-class callable of a built-in with several variants, like max(...),
is a union of one closure per variant, but the closure is one: any variant
that fits makes it acceptable, like the string 'max' already was. Union
members that are closures with equal origins now answer acceptance and
subtyping together, or-ed. RuleLevelHelper::transformAcceptedType() kept
the origin off the closures it rebuilt, so the members could not be matched.

Amp-Thread-ID: https://ampcode.com/threads/T-01a1c541-317f-7386-a2ed-9cbd66178685
… static

PHP binds no object to the closure of a static method, nor to a partial
application of a function: bindTo() with an object returns null for them.
A function's first-class callable stays bindable, and the closure of an
instance method keeps its $this, so they stay as they were.

Amp-Thread-ID: https://ampcode.com/threads/T-01a1c541-317f-7386-a2ed-9cbd66178685
…lee is

A variadic placeholder before another argument, and partial application
combined with unpacking, are compile errors in PHP, but they were only
reported once the callee resolved: undefinedFn(..., ?) or $mixed(..., ?)
went unreported. The callable rules now check the placements first and
report only them, since nothing else about such a call matters.

A second variadic placeholder is reported like PHP does, "Variadic
placeholder may only appear once.", and no closure signature is inferred
for it.

Amp-Thread-ID: https://ampcode.com/threads/T-01a1c541-317f-7386-a2ed-9cbd66178685
Calling $closure->__invoke() returned mixed and took any arguments, and its
first-class callable and partial applications, $closure->__invoke(...) and
$closure->__invoke(1, ?), lost the closure's parameters. __invoke() now
takes the closure's parameters and returns its return type, like call()
does after the object it binds.

Amp-Thread-ID: https://ampcode.com/threads/T-01a1c541-317f-7386-a2ed-9cbd66178685
PHP keeps the object a method was called on as the $this of its closure:
$object->method(...)->bindTo(null), like the same of a partial application,
returns null with a warning. Closure::__invoke(...) is the closure itself,
so it stays unbindable or not like the closure is.

Amp-Thread-ID: https://ampcode.com/threads/T-01a1c541-317f-7386-a2ed-9cbd66178685
A function calling func_get_args() takes more arguments than its parameters,
and the variadic placeholder forwards a call's extra arguments to it, so
f(?, ...)(1, 2, 3) is a call PHP passes all three to. The closure was
variadic only when the callee had a variadic parameter.

Amp-Thread-ID: https://ampcode.com/threads/T-01a1c541-317f-7386-a2ed-9cbd66178685
…does

PHP calls a method it does not declare through the __call() or
__callStatic() trampoline, (mixed ...$arguments), so the closure of its
partial application takes its placeholders as $arguments0, $arguments1...,
whatever names @method gives the parameters, and a named placeholder makes
creating it throw. Calling the closure with the @method names was accepted
although PHP rejects them as unknown.

Amp-Thread-ID: https://ampcode.com/threads/T-01a1c541-317f-7386-a2ed-9cbd66178685
Combining the variants () and ($min, $max) of mt_rand() accepted mt_rand(?),
so the count is checked against the closest variant, as for a call.

Amp-Thread-ID: https://ampcode.com/threads/T-01a1c541-317f-7386-a2ed-9cbd66178685
php-src stubs declare parameters like mt_rand()'s $min or array_keys()'s
$filter_value with the default UNKNOWN. PHP throws "must be passed
explicitly, because the default value is not known" when a later named
argument skips such a parameter, or when ... of a partial application
leaves it out. The default is now an ErrorType that every variant keeps,
so calls, closure calls and partial applications report it, and such a
partial application infers Closure. Calls like mt_rand(max: 5) crashed
ArgumentsNormalizer before.

A named argument now only selects the variants that have its parameter,
so session_set_save_handler($open, read: $read) is checked against the
signature with $close instead of the one with SessionHandlerInterface.

Amp-Thread-ID: https://ampcode.com/threads/T-01a1c541-317f-7386-a2ed-9cbd66178685
…src signature

PHP resolves named arguments against the one arginfo generated from the
function's stub, so a named call to a multi-variant built-in resolves
against its php-8-stubs signature instead of a renamed copy of each
functionMap variant. Its argument count is then checked against the
variants like a positional call's, which reports mt_rand(min: 1).

First-class callables of such functions and methods resolve named
arguments the same way when the closure is called.

Amp-Thread-ID: https://ampcode.com/threads/T-01a1c541-317f-7386-a2ed-9cbd66178685
@ondrejmirtes
ondrejmirtes merged commit ec58f0e into 2.3.x Nov 15, 2026
@ondrejmirtes
ondrejmirtes deleted the pfa-signatures branch November 15, 2026 11:21
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Support Partial Function Application

1 participant