Contrib.social

Adopt phpstan phpdoc types as canonical reference of allowed types

Open on Drupal.org →
Created on 15 August 2024, 5 months ago
Updated 12 September 2024, 4 months ago

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

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 →

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)

Tags that indicate the type of a variable, of a parameter, or of the return value of a function/method (@var, @param, @return) must be 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

  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
    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 →

✨ Feature request
Status

Active

Component

Coding Standards

Created by

🇦🇺Australia mstrelan

Live updates comments and jobs are added and updated live.
Sign in to follow issues

Comments & Activities

contrib.social Blog FAQ Discussions
Production build 0.71.5 2024