[TASK] Document php:method signature parser limitations

[CybotTM]

The php:method signature parser rejects modern PHP type syntax (?string, union types) with build warnings or wrong output, and the page currently does not mention it. This documents the limitation and the :returntype:/:param: workaround, plus a short note that array-based configuration (TCA, FlexForm, YAML) belongs in confval rather than the PHP domain.

[linawolf]

I feel like we should maybe fix the parser to also accept modern PHP syntax and open an issue in https://github.com/TYPO3-Documentation/guides-php-domain

[CybotTM]

Agreed on fixing the parser — and going through MethodNameService for that turned up an error in this PR, which I corrected in 90c2ac1.

The restriction is not "nullable and union types in the signature". METHOD_SIGNATURE_REGEX is /^\s*(\w+)\s*\(\s*(.*?)\s*\)\s*(?::\s*(\w+))?\s*$/: the parameter list is (.*?) and therefore unrestricted, while the return type after the colon is (\w+). Measured against the regex:

signature	result
retrieve(string $id): string	ok
retrieve(?string $id): string	ok
retrieve(string|null $id)	ok
retrieve(string $id): ?string	rejected
retrieve(string $id): string|null	rejected
retrieve(string $id): \Vendor\Thing	rejected

So parameters were never the problem, and the advice to give a nullable parameter a null default was pointless. The page now names the return type as the restriction and keeps the field-list workaround.

Happy to open the issue in guides-php-domain with those cases — a fully qualified return type failing is arguably the more annoying half. Say the word and I will file it there.

[CybotTM]

Closing this in favour of fixing the parser, as you suggested: TYPO3-Documentation/guides-php-domain#54.

Going through MethodNameService for that turned up more than the return type. The parameter list is split with preg_split('/\s*,\s*/'), so a comma inside a default value splits the parameter — paginate(array $range = [1, 2], int $page = 1) yields four parameters instead of two. Both defects come from matching a signature with patterns, so that PR hands the splitting to token_get_all() instead.

One detail worth having here: the lexer is used without TOKEN_PARSE, because that flag would validate against the grammar of the PHP version doing the rendering — 8.2.32 in the current render-guides image — and a manual documenting PHP 8.4 syntax would then fail to render, with a CompileError that a catch (ParseError) does not even contain.

If the fix lands, this page has nothing left to warn about. If you would rather document the limitation in the meantime, say so and I will reopen it with the corrected text — the version on the branch already names the return type as the restriction and describes what a rejected signature actually does.