Drobnost, která odstraňuje jednu otravnou duplicitu. PHP 8.6 umožňuje napsat dokumentační komentář přímo u parametru.
Doteď se parametr musel pojmenovat dvakrát, jednou v hlavičce funkce a podruhé v anotaci @param:
<?php
/**
* Vyhledá příspěvky.
*
* @param string $dotaz Hledaný výraz
* @param int $pocet Maximální počet vrácených záznamů
*/
function hledat(string $dotaz, int $pocet = 10) {}
Když parametr přejmenujete a na komentář zapomenete, dokumentace se tiše rozejde s kódem. Od PHP 8.6 jde komentář napsat rovnou k parametru:
<?php
function hledat(
/** Hledaný výraz */
string $dotaz,
/** Maximální počet vrácených záznamů */
int $pocet = 10,
) {}
Případně až za parametr, ještě před čárku:
<?php
function hledat(
string $dotaz /** Hledaný výraz */,
int $pocet = 10 /** Maximální počet vrácených záznamů */,
) {}
Jak se ke komentáři dostat?
Třída ReflectionParameter dostává novou metodu getDocComment(): string|false:
<?php
foreach ((new ReflectionFunction('hledat'))->getParameters() as $parametr) {
echo $parametr->getName() . ': ' . var_export($parametr->getDocComment(), true) . "\n";
}
// dotaz: '/** Hledaný výraz */'
// pocet: '/** Maximální počet vrácených záznamů */'
Vrací celý komentář včetně /** a */, nebo false, pokud parametr žádný nemá.
Komu se to hodí?
Hlavně nástrojům, které z kódu něco generují nebo ho analyzují za běhu. DI kontejnerům, generátorům OpenAPI dokumentace nebo definicím nástrojů pro jazykové modely. Ty dneska musí parsovat blok nad funkcí a párovat @param podle jména.
RFC prošlo v poměru 23 : 0 (4 se zdrželi) a nepřináší žádnou zpětnou nekompatibilitu, protože dřív se takový komentář prostě zahodil.
Zajímavé bude sledovat, jestli si to osvojí i PHPStan, Psalm a PhpStorm. Do té doby je to spíš věc pro autory knihoven než pro běžný aplikační kód.