I would like to relaunch the discussion around the @template annotation, since multiple issues have been raised around its syntax that may justify a change. Such a change would be relatively easy before the feature is shipped in phpstan-stable.

Here is a summary of the issues that have been raised in the past:

Semantic mismatch (vs C++)

The name template refers to C++-style generics, whose semantics do not match PHPStan or Psalm semantics (who are closer to Java-style generics). It can be misleading and give wrong expectations.

Naming conflict

The name template might conflict with existing projects already using an annotation named like this (for example, Symfony uses an annotation with that name do indicate which HTML template should be used to render a controller). Because of this, PHPStan/Psalm might be confused when analyzing these projects, and these projects might be confused when importing phpstan/psalm-annotated code.

Doctrine parser

The Doctrine annotation parser will attempt to load any annotation whose name looks like a valid class name (template does). Because of this, projects that use this parser may fail when using phpstan/psalm-annotated code. (Although it is possible to tell the parser to ignore some annotations. The ignore list is case-sensitive, so it is possible to ignore phpstan's template while not ignoring Template.)

This issue actually exists for all non-standard phpDoc annotations.

of / as keywords

It has been suggested to replace the of and as keyword used for declaring an upper bound for types, by extends.

Previous discussions

Here are previous discussions I can remember:

• Support @template tag phpdoc-parser#27 (comment)
• Support & prefer "extends" as keyword of generic param type bound definition #2468

cc @mindplay-dk @muglug @Ocramius @ondrejmirtes @JanTvrdik @hrach @teohhanhui