Adopt phpstan phpdoc types as canonical reference of allowed types

All for this, I find it frustrating that the wider PHP community has adopted in Stan / Psalm / others.

Recently the PHPDoc maintainer said something relevant to this topic:

https://phpc.social/@jaapio/112797821284066042

I'm going to try to reboot the working group for @phpfig's psr-5. Goal is to write down the standards we are already using in @phpstan @phpdoc @phpstorm, @psalm and many others.
I'm looking for people that will help me once in a while to check if I do not write down things that will break these amazing tools.

Some projects have been left behind by recent innovation.

We should just allow anything, and let our approved static analyser (PHPStan) validate it. Its not really within the domain of Coding Standards to do validation.

See also, the discussion at #3309010: Support PHPDoc Types in @param @var @return annotations →

Kind of duplicate of #3309010: Support PHPDoc Types in @param @var @return annotations → .

Badly,badly needed if Drupal will ever try to get to PHPStan level 6+.

+1, added support

Added support, Next step - can we get some proposed text before/after in the IS please? thanks!

IS said

If multiple types are possible, separate them by a vertical bar ("|").

but there's DNF types since PHP 8.2 so it needs rewording

@andypost that's the "before" section, we need to rewrite the "after" section. I'm proposing that we leave it mostly empty, and just linking off to phpstan docs.

Jumping in to give my +1 to this.

Tried a stab at the to-be text.

Note that

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.

is not what other projects do, and #3360160: Stop using FQCN in PHPDoc annotations → aims at removing it.

Agreed with #3 -- isn't this fully duplicate with #3309010: Support PHPDoc Types in @param @var @return annotations → ? Can we close this and focus efforts in one place?

Honestly now I prefer the turn that this issue has taken, and would rather close #3309010: Support PHPDoc Types in @param @var @return annotations → as duplicate at this stage.

Looks like we already have enough supporters, but fwiw +1 on this one.

Added a CR

Just pointing out that the next text is using 'must' which is not the more friendly tone that our coding standards use.

Updating issue summary.

Setting to RTBC so it can get on the agenda for a CS meeting.

I don't think there is any tone implied. It is merely communicating clearly, similar or according to RFC2119.

It would make sense for a coding standard to adopt clear language.

@dpi, I agree on having clarity but we should keep in mind that the Drupal Standards do not follow RFC2119. See ✨ Revise coding standards to use IETF RFC 2119 standards Closed: won't fix .

Changed the wording.

Change record looks good.

+1 this change and the change record both look good to me

+1 for this change. PHPStan annotations allow doing more explicit return types and detecting more bugs and issues before it goes live.

This was discussed at the Coding Standards Meeting Tuesday 2025-02-26 0900 UTC 🌱 Coding Standards Meeting Tuesday 2025-02-26 0900 UTC Active and there were no objections.

This was in the meeting 26 March and there were no objections.

This was included in the last core committer meeting and there were no objections to this change.

Updating credit.

Sniffs were not discussed here. What, if any, changes are required in Coder?

Sniffs were not discussed here. What, if any, changes are required in Coder?

We don't need to change anything to allow the proposed changes, only if we want to restrict them.

I tested this by updating the @param doc on a constructor param to use a variety of different types listed in the phpstan docs. I also started putting random strings in, and they mostly passed, unless I used any of @#,.. For example, @param zDSA[]|<>D-&* $date_formatter is acceptable, but @param zDSA[]|<>D-&*# $date_formatter is not.