DocComments For Function Parameters

It passed 23 to 0, with 4 abstaining, clearing the two-thirds majority it needed. Voting closed on March 31, 2026. The RFC targets PHP 8.6, and the page marks it as implemented.

PHP can read doc comments on functions, classes, methods and properties through Reflection, but not on function parameters. Today you describe each parameter with @param in the function's doc block, which means writing each name and type twice and letting the two drift apart. This RFC from Christian Schneider lets you put a doc comment on each parameter.

Show me#

Before, with @param:

/**
* Search for entries matching query
* @param string $query  Terms to search for in database
* @param int $num  Maximum number of entries returned, default is 10
*/
function search(string $query, int $num = 10)
{
  ...
}

After, with a doc comment on each parameter:

/** Search for entries matching query */
function search(
  /** Terms to search for in database    */
  string $query,
  /** Maximum number of entries returned */
  int $num = 10
) {
  return ['foo', 'bar', 'qux'];
}

foreach (new ReflectionFunction("search")->getParameters() as $p) {
  echo $p->name . ": " . $p->getDocComment() . "\n";
}

That prints:

query: /** Terms to search for in database    */
num: /** Maximum number of entries returned */

How it works#

The RFC adds one new method to ReflectionParameter:

public function getDocComment(): string|false {}

It returns a string or false, just like getDocComment() on the other Reflection classes.

You can put the doc comment before the parameter, or after it but before the comma, a style properties already allow. Here is the "after" style from the RFC:

function search(
  string $query /** Terms to search for in database    */,
  int $num = 10 /** Maximum number of entries returned */
) {
  ...
}

Either way, the comment sits right next to the parameter it describes, and you don't repeat the name or the type.

What it means for existing code#

Nothing breaks. The RFC notes that coding style guides and auto-formatters may need to decide how to handle the new style.