[RFC] Named arguments

Hey Larry,

On Tue, May 5, 2020 at 5:29 PM Larry Garfield larry@garfieldtech.com
wrote:

The biggest use case I see is, as discussed previously, value object
constructors. "Pass an entirely untyped and undocumentable array of
parameters" is not an sufficient userland solution in my mind, but is the
only available alternative right now.

This is easily mitigated by named constructors (
https://verraes.net/2014/06/named-constructors-in-php/), which are a
good/established practice among those using value objects.

You can create multiple (meaningful) constructor signatures depending on
use-case, which is still a much safer approach than delegating this
responsibility to a caller.

My example above uses a ::fromArray() "factory" precisely for that
purpose.

Marco Pivetta

http://twitter.com/Ocramius

http://ocramius.github.com/

Hey Benjamin,

I see the PHP internal API as the main benefactor of this feature over
userland code imho. Internals realistically couldn't get "smaller APIs"
without adding many new functions instead, for example htmlspecialchars.

It takes a couple minutes to write a non-broken htmlspecialchars function
to use in your own project.

Besides that, designing a language feature to accommodate pre-existing bad
design smells a lot.

There are libraries out there trying to provide better API to what is
provided by PHP-SRC, such as https://github.com/thecodingmachine/safe:
that's an easy win, by creating adapters for bad API, instead of
language-level constructs that will haunt us forever.

The trade off from API design perspective is either providing a more
complex API by having function permutations or an OOP API, which in turn
developers have more trouble remembering. Or the more beginner approachable
way is providing a single function that is easy to remember exists, but in
turn does more things and may require a look into the documentation to see
all the options. Given we have this API already in PHP and this will not
realistically change, I think named params will be a big win.

Sorry, but no: you provide multiple constructors, each with a limited set
of arguments, each guaranteeing constraints that depend on context.

For instance, a fromArray() may check for key existence, while
fromJson() may use a JSON-Schema definition to check that all is as
required, and fromXmlPayload() may apply an XSD validator, and so on...

Number, type and lifecycle/mutability of parameters may change depending on
named constructor, and the reduced scope makes it very easy to document
requirements, and to make the API ergonomic (yes, it's actually easier to
use: surprise!).

In this example $stuff is an array which has keys. Presumably

$parameterName => $newParameterName would be equivalent to a change of key
names. Or property names on
MyInfiniteSequenceOfParametersAsProperValidatedStructure. So you get the BC
break of renaming anyways in your example.

Correct: that's a BC break on my
MyInfiniteSequenceOfParametersAsProperValidatedStructure which does not
depend on the definition of myHorribleLegacyAndOrganicallyGrownApi().

It is still a very well isolated BC scenario on a single ::fromArray()
named ctor, compared to introducing a language-level BC boundary that
crosses all existing code out there.

Now as a provider of a public API (library, framework) you can still

counter this with a BC layer:

function foo($newParameterName, $parameterName = null) {
if ($parameterName !== null) {
$newParameterName = $parameterName;
trigger_error("Using paramaterName as named parameter is
deprecated, use newParameterName instead.", E_USER_DEPRECATED);
}
/...
}

this looks ugly (because we haven't seen it before), but is not more or
less complex than the same BC / deprecation layer in fromArray with changed
option:

public static function fromArray(array $options) {
if (isset($options['parameter_name'])) {
$options['new_parameter_name'] = $options['parameter_name'];
trigger_error("Using paramaeter_name as option is deprecated, use
new_parameter_name instead.", E_USER_DEPRECATED);
}
}

So nothing much would technically change for someone who cares about BC
for their users.

In first place, I would rarely ever design a ::fromArray() API that isn't
related to serialization or configuration loading (which is another kind of
serialization, after all).

I would not look forward to maintaining BC compliance like with
foo($newParameterName, $parameterName = null), and I do not see which
added value counters this massive amount of maintenance overload.

We're chasing a non-existing problem (or feature requirement) by adding
other problems that are far greater.

Marco Pivetta

http://twitter.com/Ocramius

http://ocramius.github.com/

Hey Theodore,
http://ocramius.github.com/

On Tue, May 5, 2020 at 6:59 PM Theodore Brown theodorejb@outlook.com
wrote:

As mentioned some days ago, I see named parameters as an added liability,
rather than values.
The rationale of my negativity around the topic being that a diff like
following is now to be considered a BC break:

-function foo($parameterName) { /* ... */ }
+function foo($newParameterName) { /* ... */ }

If the function is part of your own codebase,

BC Breaks that are intra-codebase are rarely every a problem nor a point of
discussion.

an IDE can automatically
update function calls when renaming a parameter. For functions that are
part of a public API, yes, parameters shouldn't be renamed outside of
major versions. But in my experience, it's rare for function parameters
that are part of public APIs to be renamed. Do you have many real-world
examples of where this had to happen?

Parameter name changes are very much normal, since (as I already posted in
/r/php), naming is hard, and getting it right is not a one-shot effort.

Also, I haven't heard of this being a big problem in other languages

with named arguments like Python.

Good question: I guess parameter renames are avoided on purpose? Not
familiar with the python community myself, sorry.

Why do you say that? For me this feature would be extremely helpful

when calling constructors that have several optional arguments (e.g.
similar to the ParamNode example in the RFC). Maybe you consider
this a bad API,

I do in fact consider the ParamNode example in that API to be a bad
candidate for named parameters, since I'd make all of the arguments in that
signature required anyway: defaults aren't meaningful anyway, as the AST
library where it comes from has all the context to instantiate them all
(the caller, being the parser, will have all the parameters anyway).

If you were to instantiate a ParamNode from, for example, a
ReflectionParameter, you would probably add named ctor (or an indepentent
factory, if in external supporting domain) to pass all parameters as well.

If you were to add more optional fields, or use this in a context of an AST
builder (BTW, nikic/php-parser has facilities for that already) a mutator
would be efficient too:

class ParamNode extends Node {
    public function asReference(): static
    {
        $instance = clone $this;

        $instance->byRef = true;

        return $instance;
    }

but it's a very common pattern, and named arguments

will make it far easier to work with than the typical alternative of
converting arguments to an options array (which is itself a BC break
and has many other downsides as the RFC points out).

You can add as many named constructors as you want: adding
ParamNode::fromArray() is possible.

In practice, the issues around bad API (in this case, bad = lots of
optional parameters, maybe even ordered arbitrarily) are fixed by
using proper value types and structs or value objects

How can lots of optional parameters be "fixed" in practice with structs?
E.g. how would they improve the ParamNode example in the RFC? Would
it even be possible to migrate existing classes like this to structs
without a BC break?

It is possible to add more named constructors in a BC compliant way, while
it is hard to change existing public constructors:

• ::fromArray()
• ::fromReflectionProperty()
• ::make(string $name, ?ExprNode $default, ?TypeNode $type, bool $byRef, bool $variadic)
• ::makeForPHP53(string $name, ?ExprNode $default, ?TypeNode $type, bool $byRef) - no variadic support? No problem :-)
• ::makeWithCodeLocation(string $name, ?ExprNode $default, ?TypeNode $type, bool $byRef, bool $variadic, CodeCoordinates $coordinates)

All of the above are possible BC-friendly growth directions for such kind
of data structure.
They also provide better type definitions, context, naming and invariants
than a single signature that has to cover all use-cases at once.

Personally I think it's a lot simpler and more consistent to have named

arguments which can be used anywhere, including in attributes, vs.
having to implement and learn a new syntax for structs which only works
for that one use case (and may not be easy to migrate to).

No new syntax: we already have the tools.

Marco Pivetta

http://twitter.com/Ocramius

http://ocramius.github.com/

Hi Rowan,

Hi John,

I very much do like the idea of named parameters, but I do not like the specific proposal in the linked RFC at all. I think that treating named parameters simply as syntactic sugar is not a good approach. If we're going to add named parameters, I think they should actually be significant in their own right. As such, please allow me to present an alternative.

I would propose the following opt-in mechanism, which would work by treating the parameter names aspart of the function name. Doing it this way I_think_ should allow for no backwards compatibility issues with existing code and would especially give library authors full control over the naming and presentation of their APIs.

I really like some of this proposal, but I think some of it is solving a different problem.

You mention in a later e-mail that you've been heavily inspired by Swift; Swift in turn was inspired by Objective C, which was inspired by Smalltalk. This is an important piece of history, because Smalltalk doesn't actually have methods with named parameters; it has "keyword messages" whose "selectors" are things like "indexOf:startingAt:". Swift makes them look more familiar by keeping part of the name separate from what it calls "argument labels", so a method might be called "indexOf(_:startingAt:)" or "index(of:startingAt:)".

You're not wrong here, but, I think that's an (critical) implementation detail of Objective-C and Smalltalk that is not relevant here. Also, Swift does not use selectors or message passing, unless either interoperating with ObjC classes, or the code has explicitly opted-in. Normally, Swift function/method calls are statically determined at compile time in a way similar to C/C++.

Although at a glance these look like named parameters, and they solve some of the same problems, they're actually a fundamentally different concept.

They have some nice features:

• Method calls can be made to read like sentences
• The external API of the function is kept separate from the internal implementation
• You can skip over default arguments by omitting their labels
• Overloading what looks like one method, by having different methods whose names start the same but have different "argument labels", may be appealing

But there are some crucial limitations:

I don't think any of your points are downsides to the proposal. A lot of these I think boil down to the conflict between, "as an API user, I should be able to do whatever I want", and, "as an API author, I have decided my API will be used like this". I generally side with the API author being specific on how their API will be used.

• You can't call a method without using its labels; you'd need to have a separate method with a similar name and no labels

If a function/method has labels, you're required to use them. Otherwise, you can't get the benefit of using them for name-based "overloading". For example, if you have the methods

function firstIndex(of: $element) : ?int
function firstIndex(where: callable $predicate) : ?int

You can't just call $collection->firstIndex($foo), because the compiler would have no idea which method it refers to. And while you could have a function firstIndex($param) that tries to determine which specific method to call, but now you've turned a compile-time static call into a runtime check, and that might still not be sufficient, for example, if you have a collection of callables!

The labels are part of the method's name, which happen to be written inside the parenthesis. I just argue that both of those are more readable than either of these:

function firstIndexOfElement($elt) : ?int
function firstIndexMatchingPredicate(callable $predicate) : ?int

If I give my method a particular name, I expect users to call them as such. If the user doesn't like it, then they can wrap the class and provide their own alternate interface.

• Similarly, it's up to the method's author to have versions with a mixture of unlabelled and labelled parameters, so a call like "create('hello', 42, locked: true)" is only possible if that specific variant is defined

As above: a method's author is under no compulsion to do so. If I define my API to be create('hello', fontSize: 42, locked: true), then that's how I expect my users to call it.

• You can't use the labels in the "wrong" order, you have to know the order they come in; so it doesn't solve the haystack/needle problem, except by creating extra function definitions

I don't think this is a problem either. In some cases, the extra context by having the parameter names spell out a gramatically-correct sentence structure will help with memorizing the order. In other cases, the constant repetition will help. If you visually see strpos(haystack: $str, needle: $str) all over the place, it will help; but this can also be used as a way to fix the problem by completely sidestepping it, by adding new functions/methods that offer more clarity:

strpos($string, in: $haystack);
position(of: $string, in: $haystack)
indexOf($str, in: $haystack)

In those examples, the sentence-like structure of the call, which are all variations on, "what is the position of $string in $haystack?" makes it more memorable.

• Similarly, methods with large numbers of arguments are still hard to use because you need to know both the name and the relative position of the arguments you're providing (imagine defining variants with every order of the 5 bit flags in the AMQP example in my earlier e-mail)

Well, you wouldn't define variants for each order, you'd just rely on the compiler (or IDE) to help the user. So if I tried to call

$channel->queue_declare('name', arguments: $args, durable: true)

I'd expect the compiler to report back something along the lines of, "parameters are in the wrong order; use queue_declare(_: passive: durable: exclusive: autodelete: nowait: arguments: ticket:)". Maybe even prefix or postfix the parameter names with a ? to indicate the ones that are optional because there's a default value.

Yes, you could add additional function definitions to handle whatever random order people want to use functions in, but you don't have to, and most API authors probably wouldn't. Because there's generally only a few "correct" ways to word most sentences. In that regard, AMQP::queue_declare is a pathological exception. There may be a good reason for its specific order, but lacking that knowledge, it appears to be completely arbitrary and nonintuitive.

If I said to someone, "language the hard improve working We constantly PHP to are", they'd probably look at me funny. We don't accept people speaking human language with randomized word order; neither should API authors (or other developers) be expected to accept people using APIs with randomized parameter orders.

It would be possible to take the "outside name is different from inside name" concept and apply it to named parameters proper. But the problems I would like to solve with named parameters wouldn't be solved by Swift/Smalltalk style functions.

Regards,

--
Rowan Tommins (né Collins)
[IMSoP]

-John

W dniu 06.05.2020 o 09:43, Christoph M. Becker pisze:

I'm on the fence when it comes to the feature itself so I will skip that
part entirerly but I'd like to draw attention to one more problem. Many
PHP Manual translations translate the parameter names, too - both in
text, as well as in the function/method signatures themselves.

We would need to fix every such occurence for every language (at least
active ones but there are still couple of them). Otherwise documentation
will become highly misleading.

Most people probably use IDEs of course but it still doesn't change the
fact that the manual cannot be totally out of sync with what could
become the language syntax.

I hope that we will be able to generate the <methodsynopsis> elements
automatically from the stubs (which would likely require some more
meta-information in the doc blocks). These could then automatically be
injected into the docs. Of course, someone would have to contribute the
required scripts. :)

--
Christoph M. Becker

That would surely simplify things but that's just the part of the job to
do. There are also inline mentions. Of course, they are wrapped in
<parameter> so we could try to convert them, too but this could be a bit
error prone IMO and probably would make documentation a bit unreadable
if you e.g. inject an English word in the middle of German/Polish
sentence.

Of course this should not be a blocker if the internals will decide that
we want the named parameters. I'm not trying to stop the movement here.
It's simply one more thing to consider :)

Cheers,
Maciej

Am 29.05.2020 um 21:02 schrieb Larry Garfield larry@garfieldtech.com:

Hi internals,

I've recently started a thread on resurrecting the named arguments
proposal (https://externals.io/message/109549), as this has come up
tangentially in some recent discussions around attributes and around object
ergonomics.

I've now updated the old proposal on this topic, and moved it back under
discussion: https://wiki.php.net/rfc/named_params

Relative to the last time I've proposed this around PHP 5.6 times, I think
we're technically in a much better spot now when it comes to the support
for internal functions, thanks to the stubs work.

I think the recent acceptance of the attributes proposal also makes this a
good time to bring it up again, as phpdoc annotations have historically had
support for named arguments, and this will make migration to the
language-provided attributes smoother.

Regarding the question of what to do with regard to LSP validation and
parameter names changing during inheritance: During internal discussion,
the following option has come up as a possible compromise:

1. When calling a method, also allow using parameter names from the parent
   class/interface.
2. During inheritance, enforce that the same parameter name is not used at
   different positions.

This ensures that renaming parameter names during inheritance does not
break code relying on parameter names of the parent method. At the same
time, it prohibits genuine LSP violations, where a parameter has been moved
to a different position.

I've run some static analysis to detect cases that would be affected by the
latter check, with these results:
https://gist.github.com/nikic/6cc9891381a83b8dca5ebdaef1068f4d The first
signature is the child method, and the second the parent method. I did not
put in the effort to make this completely precise, so there's both false
positives and false negatives here. But it should be enough for a general
impression. And the general impression is that these are indeed legitimate
LSP violations.

This approach would be an alternative to either silently ignoring the issue
(as the RFC proposed), or to warning for all parameter renames.

Regards,
Nikita

Just to make sure I follow what you're proposing, given:

class P {
public function foo($a, $b, $c) { ... }
}

This is legal:

class A extends P {
public function foo($a2, $b, $c) {}
}

// Mean the same thing:
$a = (new A)->foo(a = 1, b = 2, c = 3);
$a = (new A)->foo(a2 = 1, b = 2, c = 3);

This will parse error:

class A extends P {
public function foo($b, $a, $c) {}
}

Am I following the intent correctly?

If so, that sounds like a very reasonable and safe middle-ground.

--Larry Garfield

Yes,

that's pretty much the intent - having a very small BC break surface, while still allowing for safe usage of named parameters according to both the child and parent interface.

Bob

On Fri, Jun 5, 2020 at 12:45 PM Christian Schneider cschneid@cschneid.com
wrote:

Am 05.05.2020 um 15:51 schrieb Nikita Popov nikita.ppv@gmail.com:

\I've now updated the old proposal on this topic, and moved it back
under
discussion: https://wiki.php.net/rfc/named_params

First of all I really like this approach to Named Parameters: It seems to
fit well with the rest of PHP.

Note: I'm using the key: 'value' syntax instead of key => 'value' here
but that's just because I prefer that syntax and think it more naturally
extends to stuff like the shorthand syntax under "Future Scope" but that's
not a prerequisite.

I have two questions regarding to the Named Parameters which are not
related to the LSP discussion.
They might be restrictions of the current implementation mentioned in the
RFC as opposed to design restrictions:

1. Could keywords be allowed as parameter names? Currently using class:
   'foo' throws a syntax error.
2. Could positional parameters be allowed after named parameters for
   variadic functions?

These two restrictions can be looked at separately and the only reason
I'm bringing them up together is because the use case I'm looking at is
HTML generation with something like a function div() being used as follows.
Please don't discard the two questions just because you don't like this
particular use-case, thank you ;-)
div(class: 'error',
div(class: 'title', "Error Title"),
"Detailed error description...",
)

The first issue is probably mainly a parsing issue and changing T_STRING
to identifier seems to fix it though I'm not 100% sure if there are any
drawbacks to this.

Right. It should be possible to use keywords. It's a bit harder than just
replacing T_STRING with identifier, but I don't see any fundamental reason
why it shouldn't work.

I've implemented the necessary groundwork for this in
https://github.com/php/php-src/commit/b03cafd19c01db57b89727ce77cc89a7d816077c,
so now I can say for sure that using keywords as parameter name will work
fine.

Nikita

As we're moving in on feature freeze, I plan to move this proposal forward
soonishly.

I have update the RFC to drop the syntax as an open question (I haven't
seen much opposition to the use of ":"), and to describe the possible
alternative LSP behavior at
https://wiki.php.net/rfc/named_params#parameter_name_changes_during_inheritance.

While writing this down and implementing it, I found that this has more
odd edge-cases than anticipated. Overall, I'm not sold that this approach
is worth it. It sounds nice on paper, but I strongly suspect that it solves
a problem that does not existing in practice, and will force us to keep
this patch-over mechanism indefinitely, while the real solution would have
been to fix the limited amount of code that is in the intersection of
"renames parameters" and "is actually invoked with named arguments".

Just as another reminder: I plan to put this to voting by the end of the
week.

I've also updated the RFC to make the LSP behavior a secondary vote. I'm
not convinced this is a good idea myself, but some others seemed to prefer
this approach.

Hi Nikita,

Thanks for moving this forward. Currently I work with a lot of value
objects which are constructed from an associative array (requiring
lots of manual validation), and named arguments will make it feasible
to migrate most of these to simple typed parameters that can be
statically analyzed instead. For me at least this will be one of the
nicest features in PHP 8.

I'm also looking forward to the potential future shorthand syntax
for matching parameter and variable names, which could also reduce
boilerplate in array construction and destructuring.

I'll probably vote No on the secondary "Automagically allow using
parent parameter names?" vote. This is a feature that could always be
added later without a BC break, but if it's added now it would be
hard to remove if the extra complexity causes problems. For these
rare cases it's probably better to update the parameter names to
match or stick with normal sequential arguments.

Best regards,
Theodore

On Tue, Jun 23, 2020 at 12:10 PM Nikita Popov nikita.ppv@gmail.com
wrote:

Hi internals,

I've recently started a thread on resurrecting the named arguments
proposal (https://externals.io/message/109549), as this has come up
tangentially in some recent discussions around attributes and around object
ergonomics.

I've now updated the old proposal on this topic, and moved it back under
discussion: https://wiki.php.net/rfc/named_params

Relative to the last time I've proposed this around PHP 5.6 times, I
think we're technically in a much better spot now when it comes to the
support for internal functions, thanks to the stubs work.

I think the recent acceptance of the attributes proposal also makes this
a good time to bring it up again, as phpdoc annotations have historically
had support for named arguments, and this will make migration to the
language-provided attributes smoother.

Regards,
Nikita

As we're moving in on feature freeze, I plan to move this proposal
forward soonishly.

I have update the RFC to drop the syntax as an open question (I haven't
seen much opposition to the use of ":"), and to describe the possible
alternative LSP behavior at
https://wiki.php.net/rfc/named_params#parameter_name_changes_during_inheritance
.

While writing this down and implementing it, I found that this has more
odd edge-cases than anticipated. Overall, I'm not sold that this approach
is worth it. It sounds nice on paper, but I strongly suspect that it solves
a problem that does not existing in practice, and will force us to keep
this patch-over mechanism indefinitely, while the real solution would have
been to fix the limited amount of code that is in the intersection of
"renames parameters" and "is actually invoked with named arguments".

Just as another reminder: I plan to put this to voting by the end of the
week.

I've also updated the RFC to make the LSP behavior a secondary vote. I'm
not convinced this is a good idea myself, but some others seemed to prefer
this approach.

I've made two additional changes to the proposal:

1. Explicitly mentioned attribute support in
   https://wiki.php.net/rfc/named_params#attributes1, and added it to the
   implementation (oops). ReflectionAttribute::getArguments() will also return
   named arguments to the attribute, and ReflectionAttribute::newInstance()
   will behave in the intuitive manner.

2. Added some information on internal APIs in
   https://wiki.php.net/rfc/named_params#internal_apis. The tl;dr is that
   named params are pretty much completely transparent for normal extensions,
   but there are some additional APIs if for example you want to perform a
   named param call from an extension.

In relation to this, I'm also considering to change the semantics of
call_user_func_array() to treat array elements with string keys as named
parameters, rather than simply ignoring keys. The motivation here is not so
much call_user_func_array() in particular, but various other APIs that do
the same thing, such as ReflectionMethod::invokeArgs(), which should all
behave consistently.

Relatedly, I'm wondering if something like this should be allowed:

call_user_func('strlen', str: 'foo');

I'm leaning towards "yes", in which case call_user_func_array() should be
also be treated consistently.

Regards,
Nikita