Adopt phpstan phpdoc types as canonical reference of allowed types

Problem/Motivation

A number of issues have been rejected because a @param type has been too specific, for example @param array<string, string|false>.

Instead of maintaining a definition of what is a valid param type we should lean on the wider community and "get off the island".

I propose that anything included in https://phpstan.org/writing-php-code/phpdoc-types should be allowed.

Benefits

Allowing newer param types to be used without waiting for coding standards process

Three supporters required

1. https://www.drupal.org/u/mondrake 2024-08-15
2. https://www.drupal.org/u/dpi 2024-08-15
3. https://www.drupal.org/u//larowlan 2024-09-11
4. https://www.drupal.org/u/kimpepper 2024-09-11
5. https://www.drupal.org/u/feyp 2024-09-12
6. https://www.drupal.org/u/donquixote 2025-05-05

Proposed changes

Provide all proposed changes to the Drupal Coding standards. Give a link to each section that will be changed, and show the current text and proposed text as in the following layout:

1. Indicating data types in documentation

Current text

Certain tags can include data types (@param, @return, etc.).

Syntax examples:

int
string|bool
\Drupal\Core\Database\StatementInterface
int[]
\Drupal\node\NodeInterface[]
$this
static 

Syntax notes:

• Data types can be primitive types (int, string, etc.), complex PHP built-in types (array, object, resource), or PHP classes.
• If only one data type is possible, just use its name.
• If multiple types are possible, separate them by a vertical bar ("|").
• For an array where the values are all of one particular class/interface type follow the class name by [].
• Indicate arrays of built-in PHP types by following the type name by [] (example: int[], string[], etc.).
• When you are returning the main class object ($this), use @return $this.
• When creating a new instance of the same class, use @return static.

Drupal standards notes:

• Use interface names if possible, or the most general possible class, in place of a specific class.
• Always prefix types with the fully-qualified namespace for classes and interfaces (beginning with a backslash). If the class/interface is in the global namespace, prefix by a backslash.
• You may omit the description if using @return $this or @return static.
• For the PHP built-in types, use the following names:
  • array (NOT "Array"). However, the [] syntax (see above) is preferred if appropriate. That is, if you know what the array contains, and all the elements are a particular primitive type, indicate that with string[] or \My\Class\Name[] etc. instead of using the generic "array" type.
  • bool (NOT "boolean" or "Boolean"). If only TRUE or only FALSE is a possible value, rather than either one being possible, use true or false instead of bool.
  • false (NOT "FALSE", see bool)
  • float
  • int (NOT "integer")
  • null (NOT "NULL")
  • object (NOT "stdClass")
  • resource
  • string
  • true (NOT "TRUE", see bool)

Proposed text

Tags that indicate the type of a variable, of a parameter, or of the return value of a function/method (@var, @param, @return) are compliant with the PHPDoc Type syntax as documented by PHPStan. This allows advanced static analysis of Drupal codebase.

The following additional Drupal standards are applicable:

• Use interface names if possible, or the most general possible class, in place of a specific class.
• Always prefix types with the fully-qualified namespace for classes and interfaces (beginning with a backslash). If the class/interface is in the global namespace, prefix by a backslash.
• You may omit the description if using @return $this or @return static.
• Spell the following types accordingly
  • array (NOT "Array").
  • bool (NOT "boolean" or "Boolean"). If only TRUE or only FALSE is a possible value, rather than either one being possible, use true or false instead of bool.
  • true (NOT "TRUE", see bool)
  • false (NOT "FALSE", see bool)
  • int (NOT "integer")
  • null (NOT "NULL")
  • object (NOT "stdClass")

2. Repeat the above for each page or sub-page that needs to be changed.

Remaining tasks

1. Create this issue in the Coding Standards queue, using the defined template
2. Add supporters
3. Create a Change Record
4. Review by the Coding Standards Committee
5. Coding Standards Committee takes action as required
6. Discussed by the Core Committer Committee, if it impacts Drupal Core
7. Final review by Coding Standards Committee
8. Documentation updates
   1. Edit all pages</li>
   2. Publish change record
   3. Remove 'Needs documentation edits' tag
9. If applicable, create follow-up issues for PHPCS rules/sniffs changes

For a full explanation of these steps see the Coding Standards project page