Add TemplateCovariant and TemplateContravariant attributes

Author: carlos-granados

README.md

@@ -92,14 +92,16 @@ And then install any needed extensions/plugins for the tools that you use.
 
 These are the available attributes and their corresponding PHPDoc annotations:
 
-| Attribute                             | PHPDoc Annotations |
-|---------------------------------------|--------------------|
-| [IsReadOnly](doc/IsReadOnly.md)       | `@readonly`        |
-| [Param](doc/Param.md)                 | `@param`           |
-| [Property](doc/Property.md)           | `@property` `@var` |
-| [PropertyRead](doc/PropertyRead.md)   | `@property-read`   |
-| [PropertyWrite](doc/PropertyWrite.md) | `@property-write`  |
-| [Returns](doc/Returns.md)             | `@return`          |
-| [Template](doc/Template.md)           | `@template`        |
-| [Type](doc/Type.md)                   | `@var` `@return`   |
+| Attribute                                             | PHPDoc Annotations        |
+|-------------------------------------------------------|---------------------------|
+| [IsReadOnly](doc/IsReadOnly.md)                       | `@readonly`               |
+| [Param](doc/Param.md)                                 | `@param`                  |
+| [Property](doc/Property.md)                           | `@property` `@var`        |
+| [PropertyRead](doc/PropertyRead.md)                   | `@property-read`          |
+| [PropertyWrite](doc/PropertyWrite.md)                 | `@property-write`         |
+| [Returns](doc/Returns.md)                             | `@return`                 |
+| [Template](doc/Template.md)                           | `@template`               |
+| [TemplateContravariant](doc/TemplateContravariant.md) | `@template-contravariant` |
+| [TemplateCovariant](doc/TemplateCovariant.md)         | `@template-covariant`     |
+| [Type](doc/Type.md)                                   | `@var` `@return`          |
 

doc/TemplateContravariant.md

@@ -0,0 +1,26 @@
+# `TemplateContravariant` Attribute
+
+This attribute is the equivalent of the `@template-contravariant` annotation. It can be applied to a class, trait or interface.
+
+## Arguments
+
+The attribute accepts one string that defines the name of the type variable and an optional string that defines its type. The attribute itself does not have a knowledge of which type variables are valid and which are not and this will depend on the implementation for each particular tool.
+
+We aim to accept all the type variables accepted by static analysis tools for the `@template-contravariant` annotation.
+
+If the class has more than one type variable, you can add a list of `TemplateContravariant` attributes.
+
+## Example usage
+
+```php
+<?php
+
+use Exception;
+use PhpStaticAnalysis\Attributes\TemplateContravariant;
+
+#[TemplateContravariant('T')]
+#[TemplateContravariant('T', Exception::class)]
+class TemplateContravariantExample
+{
+}
+```

doc/TemplateCovariant.md

@@ -0,0 +1,26 @@
+# `TemplateCovariant` Attribute
+
+This attribute is the equivalent of the `@template-covariant` annotation. It can be applied to a class, trait or interface.
+
+## Arguments
+
+The attribute accepts one string that defines the name of the type variable and an optional string that defines its type. The attribute itself does not have a knowledge of which type variables are valid and which are not and this will depend on the implementation for each particular tool.
+
+We aim to accept all the type variables accepted by static analysis tools for the `@template-covariant` annotation.
+
+If the class has more than one type variable, you can add a list of `TemplateCovariant` attributes.
+
+## Example usage
+
+```php
+<?php
+
+use Exception;
+use PhpStaticAnalysis\Attributes\TemplateCovariant;
+
+#[TemplateCovariant('T')]
+#[TemplateCovariant('T', Exception::class)]
+class TemplateCovariantExample
+{
+}
+```

phpstan.neon

@@ -13,4 +13,4 @@ parameters:
     - '#^Parameter \#1 \.*\$[a-zA-Z]+ of attribute class PhpStaticAnalysis\\Attributes\\[a-zA-Z]+ constructor expects string, int given.$#'
     - '#^PHPDoc tag @[a-zA-Z]+ has invalid value \(\): Unexpected token "\\n ", expected type at offset [0-9]+$#'
     - '#^Attribute class PhpStaticAnalysis\\Attributes\\[a-zA-Z]+ constructor invoked with [0-9]+ parameter(s)?, [0-9]+ required.$#'
-    - '#^Attribute class PhpStaticAnalysis\\Attributes\\[a-zA-Z]+ is not repeatable but is already present above the (property|method).$#'
+    - '#^Attribute class PhpStaticAnalysis\\Attributes\\[a-zA-Z]+ is not repeatable but is already present above the (property|method).$#'

src/TemplateContravariant.php

@@ -0,0 +1,22 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PhpStaticAnalysis\Attributes;
+
+use Attribute;
+
+#[Attribute(
+    Attribute::TARGET_CLASS |
+    Attribute::TARGET_METHOD |
+    Attribute::TARGET_FUNCTION |
+    Attribute::IS_REPEATABLE
+)]
+final class TemplateContravariant
+{
+    public function __construct(
+        string $name,
+        ?string $of = null
+    ) {
+    }
+}

src/TemplateCovariant.php

@@ -0,0 +1,22 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PhpStaticAnalysis\Attributes;
+
+use Attribute;
+
+#[Attribute(
+    Attribute::TARGET_CLASS |
+    Attribute::TARGET_METHOD |
+    Attribute::TARGET_FUNCTION |
+    Attribute::IS_REPEATABLE
+)]
+final class TemplateCovariant
+{
+    public function __construct(
+        string $name,
+        ?string $of = null
+    ) {
+    }
+}

tests/TemplateContravariantTest.php

@@ -0,0 +1,59 @@
+<?php
+
+declare(strict_types=1);
+
+use PhpStaticAnalysis\Attributes\Param;
+use PhpStaticAnalysis\Attributes\TemplateContravariant;
+use PHPUnit\Framework\TestCase;
+
+#[TemplateContravariant('TClass', Exception::class)]
+class TemplateContravariantTest extends TestCase
+{
+    public function testClassTemplateContravariant(): void
+    {
+        $reflection = new ReflectionClass($this);
+        $this->assertEquals(['TClass of Exception'], self::getTemplateContravariantsFromReflection($reflection));
+    }
+
+    public function testTraitTemplateContravariant(): void
+    {
+        $reflection = new ReflectionClass(TemplateContravariantTestTrait::class);
+        $this->assertEquals(['TTrait'], self::getTemplateContravariantsFromReflection($reflection));
+    }
+
+    public function testInterfaceTemplateContravariant(): void
+    {
+        $reflection = new ReflectionClass(TemplateContravariantTestInterface::class);
+        $this->assertEquals(['TInterface'], self::getTemplateContravariantsFromReflection($reflection));
+    }
+
+    public static function getTemplateContravariantsFromReflection(
+        ReflectionClass $reflection
+    ): array {
+        $attributes = $reflection->getAttributes();
+        $templates = [];
+        foreach ($attributes as $attribute) {
+            if ($attribute->getName() === TemplateContravariant::class) {
+                $attribute->newInstance();
+                $templateData = $attribute->getArguments();
+                $templateValue = $templateData[0];
+                if (isset($templateData[1]) && $templateData[1] !== null) {
+                    $templateValue .= ' of ' . $templateData[1];
+                }
+                $templates[] = $templateValue;
+            }
+        }
+
+        return $templates;
+    }
+}
+
+#[TemplateContravariant('TTrait')]
+trait TemplateContravariantTestTrait
+{
+}
+
+#[TemplateContravariant('TInterface')]
+interface TemplateContravariantTestInterface
+{
+}

tests/TemplateCovariantTest.php

@@ -0,0 +1,59 @@
+<?php
+
+declare(strict_types=1);
+
+use PhpStaticAnalysis\Attributes\Param;
+use PhpStaticAnalysis\Attributes\TemplateCovariant;
+use PHPUnit\Framework\TestCase;
+
+#[TemplateCovariant('TClass', Exception::class)]
+class TemplateCovariantTest extends TestCase
+{
+    public function testClassTemplateCovariant(): void
+    {
+        $reflection = new ReflectionClass($this);
+        $this->assertEquals(['TClass of Exception'], self::getTemplateCovariantsFromReflection($reflection));
+    }
+
+    public function testTraitTemplateCovariant(): void
+    {
+        $reflection = new ReflectionClass(TemplateCovariantTestTrait::class);
+        $this->assertEquals(['TTrait'], self::getTemplateCovariantsFromReflection($reflection));
+    }
+
+    public function testInterfaceTemplateCovariant(): void
+    {
+        $reflection = new ReflectionClass(TemplateCovariantTestInterface::class);
+        $this->assertEquals(['TInterface'], self::getTemplateCovariantsFromReflection($reflection));
+    }
+
+    public static function getTemplateCovariantsFromReflection(
+        ReflectionClass $reflection
+    ): array {
+        $attributes = $reflection->getAttributes();
+        $templates = [];
+        foreach ($attributes as $attribute) {
+            if ($attribute->getName() === TemplateCovariant::class) {
+                $attribute->newInstance();
+                $templateData = $attribute->getArguments();
+                $templateValue = $templateData[0];
+                if (isset($templateData[1]) && $templateData[1] !== null) {
+                    $templateValue .= ' of ' . $templateData[1];
+                }
+                $templates[] = $templateValue;
+            }
+        }
+
+        return $templates;
+    }
+}
+
+#[TemplateCovariant('TTrait')]
+trait TemplateCovariantTestTrait
+{
+}
+
+#[TemplateCovariant('TInterface')]
+interface TemplateCovariantTestInterface
+{
+}