Add DefineType and ImportType attributes

Author: carlos-granados

README.md

@@ -8,7 +8,7 @@
 
 Since the release of PHP 8.0 more and more libraries, frameworks and tools have been updated to use attributes instead of annotations in PHPDocs.
 
-However, static analysis tools like PHPStan or Psalm or IDEs like PHPStorm or VS Code have not made this transition to attributes and they still rely on annotations in PHPDocs for a lot of their functionality.
+However, static analysis tools like PHPStan or Psalm or IDEs like PhpStorm or VS Code have not made this transition to attributes and they still rely on annotations in PHPDocs for a lot of their functionality.
 
 This library aims to provide a set of PHP attributes which could replace the most commonly used annotations accepted by these tools and will aim to provide related repositories with the extensions or plugins that would allow these attributes to be used in these tools.
 
@@ -84,8 +84,10 @@ These are the available attributes and their corresponding PHPDoc annotations:
 
 | Attribute                                             | PHPDoc Annotations                   |
 |-------------------------------------------------------|--------------------------------------|
+| [DefineType](doc/DefineType.md)                       | `@type`                              |
 | [Deprecated](doc/Deprecated.md)                       | `@deprecated`                        |
 | [Immutable](doc/Immutable.md)                         | `@immutable`                         |
+| [ImportType](doc/ImportType.md)                       | `@import-type`                       |
 | [Impure](doc/Impure.md)                               | `@impure`                            |
 | [Internal](doc/Internal.md)                           | `@internal`                          |
 | [IsReadOnly](doc/IsReadOnly.md)                       | `@readonly`                          |
@@ -108,12 +110,12 @@ These are the available attributes and their corresponding PHPDoc annotations:
 | [TemplateImplements](doc/TemplateImplements.md)       | `@implements` `@template-implements` |
 | [TemplateUse](doc/TemplateUse.md)                     | `@use` `@template-use`               |
 | [Throws](doc/Throws.md)                               | `@throws`                            |
-| [Type](doc/Type.md)                                   | `@var` `@return`                     |
+| [Type](doc/Type.md)                                   | `@var` `@return` `@type`             |
 
-## PHPStorm Support
-A plugin that fully supports these attributes will need to be created. Until this is ready you can get partial support by installing PHPStan, our PHPStan extension and enabling PHPStan support in PHPStorm (as described [here](https://www.jetbrains.com/help/phpstorm/using-phpstan.html)). You will then be able to see errors and messages related to these attributes in your code.
+## PhpStorm Support
+A plugin that fully supports these attributes will need to be created. Until this is ready you can get partial support by installing PHPStan, our PHPStan extension and enabling PHPStan support in PhpStorm (as described [here](https://www.jetbrains.com/help/phpstorm/using-phpstan.html)). You will then be able to see errors and messages related to these attributes in your code.
 
-Alternatively install Psalm, our Psalm extension and enable Psalm support in PHPStorm (as described [here](https://www.jetbrains.com/help/phpstorm/using-psalm.html))
+Alternatively install Psalm, our Psalm extension and enable Psalm support in PhpStorm (as described [here](https://www.jetbrains.com/help/phpstorm/using-psalm.html))
 
 ## VS Code Support
 An extension that fully supports these attributes will need to be created. Until this is ready you can get partial support by installing PHPStan, our PHPStan extension and a VS Code extension that supports PHPStan (for example [this one](https://github.com/SanderRonde/phpstan-vscode)). When you enable the extension you will be able to see errors and messages related to these attributes in your code.

doc/DefineType.md

@@ -0,0 +1,36 @@
+# `DefineType` Attribute
+
+This attribute is the equivalent of the `@type` annotation and is used to define new aliases for types and they are scoped to the class where they are defined. 
+
+We are not using the `Type` name for this attribute because that name is used for the attribute which is equivalent to the `@var` annotation. But if you prefer, you can use the `Type` attribute instead of this one to define these aliases, but we don't recommend it.
+
+## Arguments
+
+The attribute accepts one or more strings which describe the aliased type. The attribute itself does not have a knowledge of which types are valid and which are not and this will depend on the implementation for each particular tool.
+
+We expect that the attribute will be able to accept both basic types like `string` or `array` and more advanced types like `array<string>` or `Collection<int>`. We aim to accept all the types accepted by static analysis tools for the `@type` annotation.
+
+The arguments can be named arguments and the type is aliased with the name of the argument.
+
+They can also be unnamed arguments with a string that contains both the name of the alias and the aliased type, but we recommend using named arguments.
+
+If the class has more than one type alias that we want to specify, the aliases can either be declared as a list of strings for a single `DefineType` attribute or as a list of `DefineType` attributes (or even a combination of both, though we don't expect this to be actually used).
+
+## Example usage
+
+```php
+<?php
+
+use PhpStaticAnalysis\Attributes\DefineType;
+
+#[DefineType(UserAddress: 'array{street: string, city: string, zip: string}')] // this is an alias of the listed type
+#[DefineType('UserName array{firstName: string, lastName: string}')]
+#[DefineType(
+    StringArray: 'string[]',
+    IntArray: 'int[]',
+)]
+class DefineTypeExample
+{
+    ...
+}
+```

doc/ImportType.md

@@ -0,0 +1,32 @@
+# `ImportType` Attribute
+
+This attribute is the equivalent of the `@import-type` annotation and is used to import aliases for types from another class. 
+
+## Arguments
+
+The attribute accepts one or more strings which list the class from which the aliased type neeeds to be imported. The attribute itself does not have a knowledge of which types are valid and which are not and this will depend on the implementation for each particular tool.
+
+The arguments can be named arguments and the type is aliased with the name of the argument and the value is the name of the class from which it needs to be imported.
+
+They can also be unnamed arguments with a string that contains both the name of the alias and the name of the class from which it needs to be imported, but we recommend using named arguments.
+
+If the class has more than one type alias that we want to specify, the aliases can either be declared as a list of strings for a single `ImportType` attribute or as a list of `ImportType` attributes (or even a combination of both, though we don't expect this to be actually used).
+
+## Example usage
+
+```php
+<?php
+
+use PhpStaticAnalysis\Attributes\ImportType;
+
+#[ImportType(UserAddress: User::class)] // this type is imported from the user class
+#[ImportType('UserName from User')]
+#[ImportType(
+    stringArray: 'StringClass',
+    intArray: 'IntClass',
+)]
+class ImportTypeExample
+{
+    ...
+}
+```

doc/Template.md

@@ -28,7 +28,7 @@ class TemplateExample
     }
 
     // Type variable with a type
-    #[Template('T', Exception::class)]
+    #[Template('T', of:Exception::class)]
     public function methodWithTemplate(array $param)
     {
     }

doc/TemplateContravariant.md

@@ -19,7 +19,7 @@ use Exception;
 use PhpStaticAnalysis\Attributes\TemplateContravariant;
 
 #[TemplateContravariant('T')]
-#[TemplateContravariant('T', Exception::class)]
+#[TemplateContravariant('T', of:Exception::class)]
 class TemplateContravariantExample
 {
 }

doc/TemplateCovariant.md

@@ -19,7 +19,7 @@ use Exception;
 use PhpStaticAnalysis\Attributes\TemplateCovariant;
 
 #[TemplateCovariant('T')]
-#[TemplateCovariant('T', Exception::class)]
+#[TemplateCovariant('T', of:Exception::class)]
 class TemplateCovariantExample
 {
 }

doc/Type.md

@@ -6,19 +6,24 @@ We could not use `Var` for the name of this attribute because `var` is a reserve
 
 This attribute can also be used instead of using the `Returns` attribute to specify the type of the return value of a function or method, replacing the `@return` annotation.
 
+This attribute can also be used instead of using the `DefineType` attribute to specify an alias for a type, replacing the `@type` annotation.
+
 ## Arguments
 
 The attribute accepts a string which describes the type of the class property, constant or return value. The attribute itself does not have a knowledge of which types are valid and which are not and this will depend on the implementation for each particular tool.
 
 We expect that the attribute will be able to accept both basic types like `string` or `array` and more advanced types like `array<string>` or `Collection<int>`. We aim to accept all the types accepted by static analysis tools for the `@var` annotation.
 
+If used to replace the `@type` tag, the value should be a string that includes both the name of the alias and the type being aliased.
+
 ## Example usage
 
 ```php
 <?php
 
 use PhpStaticAnalysis\Attributes\Type;
 
+#[Type('FloatArray float[]')]
 class TypeExample
 {
     #[Type('string')] // the type of this constant

src/DefineType.php

@@ -0,0 +1,19 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PhpStaticAnalysis\Attributes;
+
+use Attribute;
+
+#[Attribute(
+    Attribute::TARGET_CLASS |
+    Attribute::IS_REPEATABLE
+)]
+final class DefineType
+{
+    public function __construct(
+        string ...$types
+    ) {
+    }
+}

src/ImportType.php

@@ -0,0 +1,19 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PhpStaticAnalysis\Attributes;
+
+use Attribute;
+
+#[Attribute(
+    Attribute::TARGET_CLASS |
+    Attribute::IS_REPEATABLE
+)]
+final class ImportType
+{
+    public function __construct(
+        string ...$from
+    ) {
+    }
+}

src/Type.php

@@ -7,6 +7,7 @@
 use Attribute;
 
 #[Attribute(
+    Attribute::TARGET_CLASS |
     Attribute::TARGET_CLASS_CONSTANT |
     Attribute::TARGET_PROPERTY |
     Attribute::TARGET_METHOD |

tests/DefineTypeTest.php

@@ -0,0 +1,41 @@
+<?php
+
+declare(strict_types=1);
+
+use PhpStaticAnalysis\Attributes\DefineType;
+use PHPUnit\Framework\TestCase;
+
+#[DefineType(UserAddress: 'array{street: string, city: string, zip: string}')]
+#[DefineType('UserName array{firstName: string, lastName: string}')]
+#[DefineType(
+    StringArray: 'string[]',
+    IntArray: 'int[]',
+)]
+class DefineTypeTest extends TestCase
+{
+    public function testClassTypes(): void
+    {
+        $reflection = new ReflectionClass($this);
+        $this->assertEquals([
+            0 => 'UserName array{firstName: string, lastName: string}',
+            'UserAddress' => 'array{street: string, city: string, zip: string}',
+            'StringArray' => 'string[]',
+            'IntArray' => 'int[]',
+        ], self::getPropertiesFromReflection($reflection));
+    }
+
+    public static function getPropertiesFromReflection(
+        ReflectionClass $reflection
+    ): array {
+        $attributes = $reflection->getAttributes();
+        $properties = [];
+        foreach ($attributes as $attribute) {
+            if ($attribute->getName() === DefineType::class) {
+                $attribute->newInstance();
+                $properties = array_merge($properties, $attribute->getArguments());
+            }
+        }
+
+        return $properties;
+    }
+}

tests/ImportTypeTest.php

@@ -0,0 +1,52 @@
+<?php
+
+declare(strict_types=1);
+
+use PhpStaticAnalysis\Attributes\DefineType;
+use PhpStaticAnalysis\Attributes\ImportType;
+use PHPUnit\Framework\TestCase;
+
+#[ImportType(UserAddress: User::class)]
+#[ImportType('UserName from User')]
+#[ImportType(
+    StringArray: 'User',
+    IntArray: 'User',
+)]
+class ImportTypeTest extends TestCase
+{
+    public function testClassTypes(): void
+    {
+        $reflection = new ReflectionClass($this);
+        $this->assertEquals([
+            0 => 'UserName from User',
+            'UserAddress' => 'User',
+            'StringArray' => 'User',
+            'IntArray' => 'User',
+        ], self::getPropertiesFromReflection($reflection));
+    }
+
+    public static function getPropertiesFromReflection(
+        ReflectionClass $reflection
+    ): array {
+        $attributes = $reflection->getAttributes();
+        $properties = [];
+        foreach ($attributes as $attribute) {
+            if ($attribute->getName() === ImportType::class) {
+                $attribute->newInstance();
+                $properties = array_merge($properties, $attribute->getArguments());
+            }
+        }
+
+        return $properties;
+    }
+}
+
+#[DefineType(UserAddress: 'array{street: string, city: string, zip: string}')]
+#[DefineType('UserName array{firstName: string, lastName: string}')]
+#[DefineType(
+    StringArray: 'string[]',
+    IntArray: 'int[]',
+)]
+class User
+{
+}

tests/TypeTest.php

@@ -5,8 +5,12 @@
 use PhpStaticAnalysis\Attributes\Type;
 use PHPUnit\Framework\TestCase;
 
+#[Type('FloatArray float[]')]
 class TypeTest extends TestCase
 {
+    #[Type('string')]
+    public const NAME = 'name';
+
     #[Type('string')]
     public string $property;
 
@@ -23,6 +27,18 @@ class TypeTest extends TestCase
     #[Type('string')]
     public string $propertyWithMultipleTypes;
 
+    public function testClassTemplate(): void
+    {
+        $reflection = new ReflectionClass($this);
+        $this->assertEquals('FloatArray float[]', self::getTypeFromReflection($reflection));
+    }
+
+    public function testClassConstantType(): void
+    {
+        $reflection = new ReflectionClassConstant($this, 'NAME');
+        $this->assertEquals('string', self::getTypeFromReflection($reflection));
+    }
+
     public function testPropertyType(): void
     {
         $this->assertEquals('string', $this->propertyType());
@@ -114,7 +130,7 @@ private function getMethodType(string $methodName): string
     }
 
     public static function getTypeFromReflection(
-        ReflectionProperty | ReflectionMethod | ReflectionFunction $reflection
+        ReflectionProperty | ReflectionClassConstant | ReflectionMethod | ReflectionFunction | ReflectionClass $reflection
     ): string {
         $attributes = $reflection->getAttributes();
         $type = '';