Skip to content

Tag reference

@template-covariant

@template-covariant declares a generic type parameter exactly like @template, but with an extra promise attached: the parameter is only ever used in “output” positions — return types — never accepted as an argument. That promise is what lets a static analyzer treat Collection<Dog> as a subtype of Collection<Animal> whenever Dog is a subtype of Animal, a substitution an ordinary invariant @template parameter does not permit, since the analyzer cannot otherwise rule out the parameter being consumed somewhere in a way that substitution would break.

Grammar

"@phpstan-template-covariant" <Name> [ "of" <Type> ] [ "=" <Type> ] [ <Description> ]
"@psalm-template-covariant" <Name> [ "of" <Type> ] [ "=" <Type> ] [ <Description> ]
"@template-covariant" <Name> [ "of" <Type> ] [ "=" <Type> ] [ <Description> ]

Examples

A read-only collection whose item type only ever comes out, never goes in.
/**
* @template-covariant T
*/
final class Collection
{
/** @param T $item */
private function __construct(private readonly mixed $item) {}
/** @return T */
public function get(): mixed
{
return $this->item;
}
}

Names by platform

phpstan
@phpstan-template-covariant
psalm
@psalm-template-covariant
standard
@template-covariant

Parsing a @template-covariant tag produces the same kind of tag as @template, exposing $parameter, $bound, and $default; see @template for what each of those means and how the "of" and "=" clauses work.

final class TemplateCovariantTag extends TypeParameterTag
{
// Same $parameter/$bound/$default shape as TemplateTag.
}

The opposite variance is @template-contravariant, for parameters used only as input.

Both PHPStan and Psalm give @template-covariant dedicated coverage of their own: PHPStan’s write-up on template-covariant and Psalm’s templated annotations.