Logo Questions Linux Laravel Mysql Ubuntu Git Menu
 

PHPDoc: Documenting a function with a variable number of arguments

Tags:

php

phpdoc

People also ask

Can we pass a variable number of arguments to a function?

When you call a function in JavaScript, you can pass in any number of arguments, regardless of what the function declaration specifies. There is no function parameter limit.

Which function accepts a variable number of arguments?

In mathematics and in computer programming, a variadic function is a function of indefinite arity, i.e., one which accepts a variable number of arguments.

What is a variable number of arguments?

To call a function with a variable number of arguments, simply specify any number of arguments in the function call. An example is the printf function from the C run-time library. The function call must include one argument for each type name declared in the parameter list or the list of argument types.


If your using a variable number of arguments and also using PHP >= 5.6 then you are able to use variadic functions (allowing variable number of arguments) which still conforms to the PHPDoc ,... syntax already mentioned and PHPStorm will interpret the docs properly as well. Using variadic functions eliminates needing func_get_args() to capture arguments into an array.

/**
 * @param mixed $args,... Explainatorium!
 */
function variadiculous(...$args) {
    // NOTE: $args === func_get_args()
    foreach ( $args as $arg ) {
        /* do work */
    }
}

PHPStorm will auto-generate the docs as @param array $args because technically when inside the function variadiculous is_array($args) is true. I change it to read @param mixed $args,... as above and when I use the hotkey to display a function signature from somewhere else in my code PHPStorm displays variadiculous($args : ...array|mixed) -- I recommend using this method if your using PHP >= 5.6


/**
 * @param mixed $numbers,... Description
 */
Public function sum ($numbers)

In the method, $numbers will not be used.


In the case of the ... syntax, PHPStorm 2017.1 uses:

/**
 * @param Type[] ...$values One or more values.
 */
public function func(Type ...$values) {
    // ...
}

Something worth noting is that with a doc block such as:

/**
 * @param Type[] ...$values One or more values.
 */
public function func(Type ...$values) {
    // ...
}

...it might seem like you could pass an array of Type, e.g.

Foo()->func([Type, Type, Type])

...this throws a fatal error, obviously now.

Where:

Foo()->func(...[Type, Type, Type])

...does not as you have destructured it on method call.

Anyway the point here is that I was experimenting with how PHPStorm would treat the doc block and depending on the way in which you orient your $args variable in your doc block, with either ...$args or $args,... determines the type of hints you get back in your IDE.

I'd really like a way to suggest the values you should pass by name into the method in the exemplified image below in the case where you have an optional length of function/method parameters, with a specific order in which they should be passed.

You might think, "just set default args, $arg1 = 'default', $arg2 = true" which typically makes sense but in cases

Pseudo-example:

/**
 * @param int ...$args Hour, Minute, Second, Timezone, $arg [, ...$args]
 */
public static function createA(int ...$args) {}

/**
 * @param int $args,... Hour, Minute, Second, Timezone, $arg [, ...$args]
 */
public static function createB(int ...$args) {}

/**
 * @param int[]|int $args,... Hour, Minute, Second, Timezone, $arg [, ...$args]
 */

public static function createC(int ...$args) {}

enter image description here

...so either of:

  • https://stackoverflow.com/a/38275992/1290575
  • https://stackoverflow.com/a/43622600/1290575

...is the correct answer (just keeping in mind orientaton: ...$args or $args,...)