PHPDoc type definitions - what's the standard we follow?

[fredden]

Background

This codebase uses PHPDoc tags to specify property (@var), parameter (@param), and return (@return) types. This pre-dates the same being supported in native PHP. There are plans to move these types from the comments into PHP, but in the meantime (while we still support old versions of PHP), the comments remain and should be respected.

Problem

While working on #344 (comment), it has come to light that the syntax used in these comments to specify the contents of an array is not valid according to PSR-5. The syntax seems to be widely understood and is supported by other tools, but is not documented. Additionally, there is no validation of these comments within this codebase with the current tooling¹. This leads to situations where developers must make a "best guess" for the format and trust that other humans validate the syntax during code review.

Way forward

Please can we define what syntax is valid / supported / accepted for type declarations within this codebase. This may include asking the maintainers of PSR-5 to update that document, and then pointing to this newly-updated-PSR-5 as the standard which we follow. Or we may like to point to a different standard such as that used by PHPStan.
Ideally this would include an automatic static-analysis check (perhaps with a PHP_CodeSniffer sniff) to validate the syntax of these special comments.

References

• https://github.com/php-fig/fig-standards/blob/master/proposed/phpdoc.md#arrays
• https://docs.phpdoc.org/guide/guides/types.html#arrays
• https://phpstan.org/writing-php-code/phpdoc-types#general-arrays
• https://psalm.dev/docs/annotating_code/type_syntax/array_types/#phpdoc-syntax

Footnotes

1. It is possible for PHPStan to validate these comments in their current form, but doing so requires setting a PHPStan level higher than we are able to for other reasons. There are no PHP_CodeSniffer rules in the current ruleset which validate the format of these types. ↩