[PSR-5] Variadic Parameters

[Chuck Burgess]

The current draft does not contain references to or examples of variadic parameters, since they entered the PHP language after the early PSR-5 drafts were done.  Assuming that folks agree that they should be represented in the spec, this email thread opens the discussion on the syntax to use.

Previous discussion exists here (https://github.com/phpDocumentor/fig-standards/issues/121), for background reading.

The key question on syntax is not whether to include "..." in the spec, but with whether or not "[]" should also be shown:

* @param DateInterval[] ...$intervals

vs

* @param DateInterval ...$intervals

Both are meant to imply that the variable number of parameters passed can be expected to be found inside an $intervals array of DateInterval objects.

Please reply to this thread with thoughts on this...

CRB

[Robbie Averill]

Hi Chuck,

Seeing as $intervals is an array when accessed directly from within the method (via $intervals), it seems to me that @param DateInterval[] ...$intervals would make sense.

Cheers,

Robbie

--
You received this message because you are subscribed to the Google Groups "PHP Framework Interoperability Group" group.
To unsubscribe from this group and stop receiving emails from it, send an email to php-fig+u...@googlegroups.com.
To post to this group, send email to php...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/7176991b-5b4e-4d88-adeb-9ccd3189f7a6%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

--

Robbie Averill | Senior Developer

04 978 7330

http://silverstripe.com/

[Woody Gilk]

I agree with Chuck's analysis, as it follows closely with how the code
is written.
--
Woody Gilk
https://shadowhand.me

> To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/CANv6TC1XyHBVnj1siXkQcHH3SNahVrsRBLSf7XTy1v2Bmh6T5g%40mail.gmail.com.

[Stefano Torresi]

Hey list,

what if one wanted to hint to a varable number of arrays of DateInterval?

e.g. `func(array ...$intervals) {}`

Isn't this what `@param DateInterval[] ...$intervals` should actually be used for?

Cheers

To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/CAGOJM6%2BG9_Pwf-NWE6JTBh1cJ%3Dqx3_3vLYU0NrBFTgAh%2BXSGqA%40mail.gmail.com.

[Larry Garfield]

I would say yes, include the []. That indicates "this thing is an array of
these thingies", making it consistent with the same usage on non-variadics.

(Unless there's some later development that would make it conflict, or it's
decided to reuse the syntax for something else, but for now, include the [].)

--Larry Garfield

[Daniel Hunsaker]

Any reason not to consider another variant which may be clearer than either of the current proposals? For example:

* @param DateInterval[...] $intervals

This syntax indicates the value is an array, but is generated as such from a variadic list, rather than passing an actual array. That then allows support for something like the following to clearly address Stefano's scenario, above:

* @param DateInterval[][...] $intervals

I understand that the elipsis alone indicates a variadic list of arguments will be passed into the function/method as an array for PHP's sake, but documentation is for humans (and IDEs to a lesser degree), so deviating from it slightly in this way seems reasonable, at least to this particular human.

- Dan Hunsaker

--
You received this message because you are subscribed to the Google Groups "PHP Framework Interoperability Group" group.
To unsubscribe from this group and stop receiving emails from it, send an email to php-fig+u...@googlegroups.com.
To post to this group, send email to php...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/1539639684.104789.1543072184.166A0219%40webmail.messagingengine.com.

[Tyson Andre]

I'm in favor of @param DateIntervals ...$interval

Additionally, I'd be in favor of treating the union type differently based on whether or not "..." was before the variable in the phpdoc

/** @param DateInterval[] $intervals this supports legacy syntax */

function example(DateInterval ...$intervals) {}

/** @param DateIntervals ...$intervals this supports newer uses. I'm in favor of it because the phpdoc and real signature snippets are the same. */

function example(DateInterval ...$intervals) {}

A large number of tools expect "@param DateInterval ...$intervals" right now. I'm not aware of tools that expect @param DateInterval[] ...$intervals (with both [] and ... simultaneously) but they'd be relevant to this discussion.

- phpStorm: https://youtrack.jetbrains.com/issue/WI-29429 (Marked as a fixed+verified usability problem)
- phan: https://github.com/phan/phan/wiki/Frequently-Asked-Questions#a-variadic-function-with-phpdoc-has-unexpected-types

- psalm: https://github.com/vimeo/psalm/blob/2.0.14/tests/VariadicTest.php#L68-L91 (providerFileCheckerValidCodeParse provides file contents and asserts that psalm doesn't warn about those
- phpstan: https://github.com/phpstan/phpstan/issues/683

- phpdocumentor: Couldn't find documentation - Possibly waiting for PSR-5 to be finalized? The implementation/tests may have changed since https://github.com/phpDocumentor/phpDocumentor2/issues/629#issuecomment-38902224

[Jan Schneider]

Agreed, feels like the most natural notation.

Zitat von Robbie Averill <rob...@silverstripe.com>:

To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/CANv6TC1XyHBVnj1siXkQcHH3SNahVrsRBLSf7XTy1v2Bmh6T5g%40mail.gmail.com.

For more options, visit https://groups.google.com/d/optout.

---

Jan Schneider
The Horde Project
https://www.horde.org/

[Jan Schneider]

That would be @param DateInterval[][] ...$intervals then.

Zitat von Stefano Torresi <ste...@torresi.io>:

To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/CAFojS1tMJGeXmzeo5_jVrSpt2UZu93iBpN195hbYKzoNHtHQxw%40mail.gmail.com.

For more options, visit https://groups.google.com/d/optout.

[Chuck Burgess]

On Monday, October 15, 2018 at 4:23:46 PM UTC-5, Stefano Torresi wrote:

Hey list,

what if one wanted to hint to a varable number of arrays of DateInterval?

e.g. `func(array ...$intervals) {}`

Isn't this what `@param DateInterval[] ...$intervals` should actually be used for?

Cheers

I had thought of this possibility soon after my original email... but was self-throttling until today to bring it up :-D

I agree with Stefano, that this use case is feasible, and thus the syntax needs to account for it.  

So, the datatype part of the syntax represents a series of DateInterval objects being passed individually, then `@param DateInterval ...$intervals`.

If it's actually a series of *arrays* that each contain DateInterval object members, then `@param DateInterval[] ...$intervals` would signify that.

CRB

[Stefano Torresi]

Thanks Chuck, 

That's what I thought, i.e. the presence of `...` already implies that the parameter is an array, so adding [] should not mean the same thing.

[Chuck Burgess]

So the last point was thinking about how to interpret

    @param DateInterval ...$intervals

versus

    @param DateInterval[] ...$intervals

Stefano and I appear to agree that the first one fits correctly with code signature

    function gatherIntervals (DateInterval ...$intervals)

where individual DateInterval objects are passed in as arguments, whereas the second one fits with

    function gatherIntervals (array ...$intervals)

where a series arrays of DateInterval objects are passed in as arguments.

Are there any further use cases to consider, such that this defined usage of "[]" with "..." will not suffice?

CRB