TypeParser: read the "|" that follows a "?" - #321

The problem

A ? written before a type ends the type: the | that may follow it is left unread, for the caller to fail on.

$typeParser->parse(new TokenIterator($lexer->tokenize('?int|null')));
// ?int, with "|null" left over

So every tag written that way is turned into an error:

@property ?int|null $handler   Unexpected token "|", expected variable at offset 18

It is not specific to null — ?int|string fails the same way — and it happens at every depth a type may be written at: array<?int|null>, list<?int|null>, array{a: ?int|null} and (?int|string) are all turned down.

Why the | can be read

?A|B is the same set of values whichever of the two the ? is read to belong to:

• (?A)|B → A|null|B
• ?(A|B) → A|B|null

There is nothing to choose between, and nothing for a reader to get wrong. The parser already reads both of those spellings when they are written with parentheses; only the plain one is turned down, so what is being rejected is the spelling rather than the type.

An & is a different matter, and this PR deliberately leaves it as it is:

• (?A)&B and ?(A&B) are not the same set

so ?A&B stays an error rather than being quietly read as one of them. PHP writes that type as (A&B)|null, and a test is added pinning the behaviour.

Where it is written

PHPDoc written from an API specification that carries its own nullable marker ends up with both markers on the same type. Discord's API reference marks a nullable field by prefixing its type with a question mark, and marks an optional field by suffixing its name with one (Nullable and Optional Resource Fields) — a ?string column there is a field that may be null.

A property transcribed from such a table carries the specification's marker and PHPDoc's own, and is written ?int|null. The two agree: the type is int|null on either reading.

Reported downstream as phpDocumentor/phpDocumentor#3987, where it surfaces as an ERROR line per tag.

On #86

#86 asked for this and was closed on the grounds that ?A|B is not valid PHP syntax, which is true and is not in dispute here — PHPDoc already reads a good deal that PHP will not (array{a: int}, list<int>, int-mask, conditional types). What that PR did not put forward, and what this one rests on, is that the union case is unambiguous and the intersection case is not, so the two can be told apart rather than refused together. It also carried no tests and no grammar. If the answer is still no, the tests here at least write the current behaviour down.

The change

• TypeParser::parse() and TypeParser::subParse() carry a nullable type into a following union, and only into a union.
• parseNullable() now enriches the node it builds with its own attributes, as parseAtomic() already does — without it the NullableTypeNode carries no line or index once it is a union member.
• doc/grammars/types.pp3 says the same, so the fuzzer generates these types and GrammarSyncTest keeps the two in step.

?A|B is read as a union whose first member is ?A, which prints back exactly as written.

Checks

• make tests — 1766 pass (16 added; no existing test changed or removed)
• FuzzyTest — 6000 generated inputs pass
• make phpstan — no errors
• make cs, make lint — clean

GrammarSyncTest::testPhpDocGrammarReadsWhatPhpDocParserReads fails for me on Windows on an unrelated @return Foo <strong> input, because of \r\n in the known-disagreement list; it fails identically on a clean checkout, so it is not from this change.

🤖 Generated with Claude Code