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

Created on 3 July 2025, 11 days 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:

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.
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.
@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}
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.

Comments & Activities

Issue created by @xjm
Comment 11 days ago →
🇺🇸United States xjm
Comment 11 days ago →
🇺🇸United States xjm
Comment 11 days ago →
🇺🇸United States xjm
Comment 11 days ago →
🇪🇸Spain fjgarlin
I’m going to change the priority of this purely for queue sorting purposes right now.

We’re working through some of the other critical issues and most of them are fixed now, so maybe we can squeeze this as this format us adopted by core and actually breaking some pages.
Comment 1 day ago →
🇨🇦Canada Charlie ChX Negyesi 🍁Canada
The clean, total solution to all problems current and future is to have a class extending PHPStan\PhpDocParser\Printer\Printer much like Drupal Pretty Printer extends the php-parser printer which inspired the phpstan phpdoc printer. This printer can put in the HTML tags which can be turned into links much like it already happens with the code. Easy.

contrib.social Blog FAQ Discussions

Production build 0.71.5 2024