Optional nullable parameters in PHPDoc

Question

Imagine that we have method with optional nullable argument (PHP 7.0) like in this example:

/**
 * @param Type1 $foo 
 * @param Type2 $bar
 */
 function myFunction(Type1 $foo, Type2 $bar = null)
 {

 }

Unfortunately it's not clear from the PHPDoc documentation, what is the right way to mark the second argument optional and nullable.

Typically I use "Type2|null" notation:

/**
 * @param Type1 $foo 
 * @param Type2|null $bar
 */
 function myFunction(Type1 $foo, Type2 $bar = null)
 {

 }

Actually this is my preferable way, because it explicitly describes all the possible types. But I heard complaints that is not obvious from the doc if the parameter is optional or not.

I'm aware of, seams like, unofficial convention "(optional)"

/**
 * @param Type1 $foo 
 * @param Type2 $bar (optional)
 */
 function myFunction(Type1 $foo, Type2 $bar = null)
 {

 }

I don't like this approach, because, technically, you can explicitly provide NULL as a second argument. And it's not clear from the phpdoc.

Generally speaking, I can even use them together:

 * @param Type2|null $bar (optional)

But it doesn't look nice, IMHO.

Could you provide me some feedback or, even better, some links to corresponding coding standards / style guides?

Phanerogam

Why would you null it if you have a Type (which intends to be a class)? Make either the Function intelligent to check at the beginning or make a additional Function with different parameters expected. – Bourbonism

This sounds like something which will tend towards opinion based more than anything. – Sannyasi

It's not about the changing the code. optional arguments smell in general. It's about phpdoc standards. Some of the people have very strong opinion about that, which surprises me as well. – Phanerogam

Answer 1

@param Type2|null $bar

is the proper way, from the perspective of phpDocumentor... see the last three arguments of the getOption() method as shown here.

Dewitt

And how about Type2 $bar = 'Default' ? In that case @param Type2|null $bar would be wrong (according to phpstan) – Afra

If you default your optional argument to something non-null, then the |null portion would not be in your type string. Instead, the tag would be @param Type2|string $bar. – Dewitt

oh gosh. Of course Type2 is not a string... Type2 $bar = Type2::getDefaultInstance() is more what I thought about :) – Afra

Well, since you can't put a function call like that into the original function's argument signature, then presumably you do want the optional null in the signature, and then in the function body a null check to trigger that getDefaultInstance() callout to populate it. So, the parameter tag would be as it is in my answer, but some additional notes could higlight that the callout occurs implicitly (either via an inline {@link} tag in the parameter description, a separate @see tag, or even an @internal tag that uses an inline {@link} in its own description). – Dewitt

yea actually I should know that. Just trying to give an example to make my point. But I guess I got stuck in the wrong direction. never mind :D – Afra