When should I use NULL in PHPDoc type hints and docblocks?

Question

I am confused about when to use the null as a type when describing variables with PHPDoc. Are type hints supposed to describe hopes and expectations for external callers to anticipate and comply with, or are they supposed to document all possible types of the variable even if the hope is it will be one very specific type in practice?

Example 1: default values. The following function only expects non-null values. But if no value is passed, it defaults to null and checks for that explicitly as a way to determine whether or not anything was passed, and returns a special value for that case. Hopefully no external caller will pass anything except an integer. Should null be used in the @param type as below, or should it only specify int since that's what we want passed if anything is passed?

/**
 * @param int|null $bar
 */
function foo($bar = null) {
  if(is_null($bar)) { 
    return 'ABC';
  }

  return doSomething($bar);
}

Example 2: instance properties. We only want $bar to contain integers. That said, if nothing is set for bar then the default PHP value for this instance property is null. Do I need to account for this every place that uses $bar, with a possible null type as below?

class Foo {
  /**
   * @var int|null
   */
  public $bar;

  /**
   * @param int|null $bar
   */
  public setBar( $bar) {
    $this->bar = $bar;
  }

  /**
   * @return int|null
   */
  public function getBar() {
    return $this->bar;
  }
}

Basically I find myself littering nearly every @param and @var declaration with |null because technically it could be that value. But in practice it shouldn't be. Should I expect nearly all of my types to contain the possibility of null or should that be assumed, and I should avoid specifying it unless I expect to set or receive a value of null explicitly?

Answer 1

In practice, I would lean towards having param tags only list what you want passed in. However, for return tags, you really do need to list every type that could possibly be returned. Here's why I differ on the two.

Since PHP is not strongly typed, even when you say "only pass in an int", your method does still need to make sure it is not passed something unexpected. Just because the method code tries to handle receiving other types, you don't want your docs to tell your users "sure, you can pass me a NULL, and I'll do something with it for you". You want your docs to say "give me an int, period".

When considering return values, your users really really really need to know every potential return type that could come back from your method, because they really need to cover their bases in their code to handle all the types that your method might return.

Answer 2

Yes, by PHPDoc standards, you should include null everywhere (if it applies, of course)

See here: http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.param.pkg.html

The datatype should be a valid PHP type (int, string, bool, etc), a class name for the type of object, or simply "mixed". Further, you can list multiple datatypes for a single parameter by delimiting them with the pipe (e.g. "@param int|string $p1"). You may document parameters listed or any optional paramters that will be parsed by standard PHP functions func_num_args()/get_func_arg(). Recommended name format for parameters listed with func_get_arg() is: $paramname if there is only one parameter $paramname,... if the number of parameters is unlimited