Contrib.social

Bugs with phpdoc data type display, especially for array types and shapes

Open on Drupal.org →
Created on 3 July 2025, about 1 month ago

Problem/Motivation

Reference: ✨ Adopt phpstan phpdoc types as canonical reference of allowed types Active .

This might be split up into a couple child issues depending on the implementation.

Recently, core formally adopted PHPStan's full list of allowed PHPDoc types. These include the standard things we're used to seeing like int|null or string[], but also a very rich syntax for array types and array and object shapes.

Miscellaneous examples quoted from that page:

  • array<int, Type>
  • non-empty-array<Type>
  • list<Type>
  • key-of<Type::ARRAY_CONST>
  • array{'foo': int, "bar": string}
  • array{0: int, 1?: int}

Various uses have already crept into the core codebase since the standard was adopted, without taking into account how it would be displayed on api.d.o. In reviewing ✨ Add note to log when site put into and taken out of Offline mode Needs work , I ended up auditing a few of these cases, and found the following:

  1. Some of the advanced types are formatted correctly for @param. Example: Look at the last two parameters of the Block attribute constructor. Those are formatted as:

    class-string|null $deriver: (optional) The deriver class.

    array<string, string|false> $forms: (optional) An array of form class names or FALSE, keyed by a string.

  2. None of the @return are formatted correctly, but this seems to be an existing issue with all return data types, not just these advanced shapes: 🐛 Format @return values the same as @param Active

    Example: DebugDump::decodeDump()'s return value, which simply has an unformatted string for the return value:

    Return value

    array{test: string, file: string|null, line: int|null, dump: string[]} An encoded string.

  3. @var parsing already seems broken if the static keyword is used. Example: DebugDump::$colors, which says:

    Type: colors

    For the code:

    private static bool $colors = FALSE;

    That said, when static (or similar) isn't used, the display of @var types is more or less okay. Example: UnpackOptions::$options:

    Type: array{ignore: string[], on-require: boolean}

  4. I have found at least one case (with nested angle brackets) where the PHPStan array type syntax definitely breaks api.d.o's parsing: the member variable HookCollectorPass::$groupIncludes. It displays as:

    Type: array<

    But the code is for the type is

     @var array<string, list<string>>

Proposed resolution

  • Properly format return types.
  • Fix the nested angle bracket array format for @var (and any similar bugs) so that parsing isn't broken.
  • Consider providing a reference to the PHPStan documentation in context?
  • Consider using PHPStan itself for parsing the data types.

Remaining tasks

TBD. May need scoping into child issues?

User interface changes

TBD

API changes

TBD

Data model changes

TBD

🐛 Bug report
Status

Active

Version

2.0

Component

Parser

Created by

🇺🇸United States xjm

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