Add Throws attribute

carlos-granados · carlos-granados · commit 911b2f74b20e · 2024-02-25T18:54:25.000+01:00
diff --git a/README.md b/README.md
@@ -116,5 +116,6 @@ These are the available attributes and their corresponding PHPDoc annotations:
 | [TemplateExtends](doc/TemplateExtends.md)             | `@extends` `@template-extends`       |
 | [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`                     |
 
diff --git a/doc/Impure.md b/doc/Impure.md
@@ -17,7 +17,7 @@ class ImpureExample
 {
     public static int $i = 0;
     
-    #[Impure]
+    #[Impure] // this function is impure
     public static function addCumulative(int $left) : int
     {
         self::$i += $left;
diff --git a/doc/IsReadOnly.md b/doc/IsReadOnly.md
@@ -17,7 +17,7 @@ use PhpStaticAnalysis\Attributes\IsReadOnly;
 
 class IsReadOnlyExample
 {
-    #[IsReadOnly]
+    #[IsReadOnly] // this property cannot be written to
     public string $name;
     
     ...
diff --git a/doc/Method.md b/doc/Method.md
@@ -19,7 +19,7 @@ If the class has more than one method that we want to specify, the signatures fo
 
 use PhpStaticAnalysis\Attributes\Method;
 
-#[Method('string getString()')]
+#[Method('string getString()')] // these methods are available
 #[Method(
     'void setString(string $text)',
     'static string staticGetter()',
diff --git a/doc/Mixin.md b/doc/Mixin.md
@@ -24,7 +24,7 @@ class A
     }
 }
 
- #[Mixin('A')]
+ #[Mixin(A::class)] // this class proxies A
 class B
 {
     public function doB(): void
diff --git a/doc/Property.md b/doc/Property.md
@@ -25,7 +25,7 @@ If the attribute is used as a replacement for the `Type` attribute for a propert
 
 use PhpStaticAnalysis\Attributes\Property;
 
-#[Property(name: 'string')]
+#[Property(name: 'string')] // these properties are available
 #[Property('int $age')]
 #[Property(
     index1: 'string[]',
diff --git a/doc/PropertyRead.md b/doc/PropertyRead.md
@@ -21,7 +21,7 @@ If the class has more than one property that we want to specify, the types for t
 
 use PhpStaticAnalysis\Attributes\PropertyRead;
 
-#[PropertyRead(name: 'string')]
+#[PropertyRead(name: 'string')] // these properties cannot be written to
 #[PropertyRead('int $age')]
 #[PropertyRead(
     index1: 'string[]',
diff --git a/doc/PropertyWrite.md b/doc/PropertyWrite.md
@@ -21,7 +21,7 @@ If the class has more than one property that we want to specify, the types for t
 
 use PhpStaticAnalysis\Attributes\PropertyWrite;
 
-#[PropertyWrite(name: 'string')]
+#[PropertyWrite(name: 'string')] // these properties cannot be read
 #[PropertyWrite('int $age')]
 #[PropertyWrite(
     index1: 'string[]',
diff --git a/doc/Pure.md b/doc/Pure.md
@@ -15,7 +15,7 @@ use PhpStaticAnalysis\Attributes\Pure;
 
 class PureExample
 {
-    #[Pure]
+    #[Pure] // this function is pure
     public static function add(int $left, int $right) : int 
     {
         return $left + $right;
diff --git a/doc/RequireExtends.md b/doc/RequireExtends.md
@@ -18,7 +18,7 @@ use PhpStaticAnalysis\Attributes\RequireExtends;
 abstract class Parent {
 }
 
-#[RequireExtends('ParentClass')]
+#[RequireExtends(Parent::class)] // needs to extend this class
 trait myTrait {
 }
 
diff --git a/doc/RequireImplements.md b/doc/RequireImplements.md
@@ -23,7 +23,7 @@ interface RequireInterface
 {
 }
 
-#[RequireImplements('RequireInterface')]
+#[RequireImplements(RequireInterface::class)] //needs to implement this interface
 trait MyTrait
 {
 }
diff --git a/doc/Returns.md b/doc/Returns.md
@@ -21,7 +21,7 @@ use PhpStaticAnalysis\Attributes\Returns;
 
 class ReturnsExample
 {
-    #[Returns('Array<string>')]
+    #[Returns('Array<string>')] // this is the return type
     public function getNames(): array
     {
         return ['Fred', 'John'];
diff --git a/doc/SelfOut.md b/doc/SelfOut.md
@@ -22,7 +22,7 @@ class SelfOutExample
 {
     #[Template('TItemValue')]
     #[Param(item: 'TItemValue')]
-    #[SelfOut('self<TValue|TItemValue>')]
+    #[SelfOut('self<TValue|TItemValue>')] // this is the new type
 	public function add($item): void
 	{
 	}	
diff --git a/doc/TemplateExtends.md b/doc/TemplateExtends.md
@@ -19,6 +19,6 @@ use PhpStaticAnalysis\Attributes\TemplateExtends;
 #[Template('T')]
 class ParentClass {}
 
-#[TemplateExtends('ParentClass<int>')]
+#[TemplateExtends('ParentClass<int>')] // type of extended class
 class ChildClass extends ParentClass {}
 ```
diff --git a/doc/TemplateImplements.md b/doc/TemplateImplements.md
@@ -23,6 +23,6 @@ use PhpStaticAnalysis\Attributes\TemplateImplements;
 #[Template('T')]
 interface TemplateInterface {}
 
-#[TemplateImplements('TemplateInterface<int>')]
+#[TemplateImplements('TemplateInterface<int>')] // this is the type of the implemented interface
 class MyClass implements TemplateInterface {}
 ```
diff --git a/doc/TemplateUse.md b/doc/TemplateUse.md
@@ -25,7 +25,7 @@ use PhpStaticAnalysis\Attributes\TemplateUse;
 #[Template('T')]
 trait TemplateTrait {}
 
-#[TemplateUse('TemplateTrait<int>')]
+#[TemplateUse('TemplateTrait<int>')] // this is the type of the used trait
 class MyClass use TemplateInterface {
     use TemplateTrait;
 }
diff --git a/doc/Throws.md b/doc/Throws.md
@@ -0,0 +1,31 @@
+# `Throws` Attribute
+
+This attribute is the equivalent of the `@throws` annotation. It can be applied to a method or function to indicate the exceptions that are thrown by them.
+
+## Arguments
+
+The attribute accepts one or more strings that define the types of exceptions that are thrown. The attribute itself does not have a knowledge of which exceptions are valid and which are not and this will depend on the implementation for each particular tool.
+
+We aim to accept all the exceptions accepted by static analysis tools for the `@throws` annotation.
+
+The arguments need to be unnamed arguments and the value should match the type of the exception thrown by the class.
+
+If the class throws more than one type of exceptions, the types of the different exceptions can either be declared as a list of strings for a single `Throws` attribute or as a list of `Throws` attributes (or even a combination of both, though we don't expect this to be actually used).
+
+## Example usage
+
+```php
+<?php
+
+use SpecialException;
+use PhpStaticAnalysis\Attributes\Throws;
+
+class MyClass use TemplateInterface {
+    
+    #[Throws(SpecialException::class)]
+    public function throwsException(): void
+    {
+        throw new SpecialException();
+    }
+}
+```
diff --git a/doc/Type.md b/doc/Type.md
@@ -21,7 +21,7 @@ use PhpStaticAnalysis\Attributes\Type;
 
 class TypeExample
 {
-    #[Type('string')]
+    #[Type('string')] // the type of this constant
     public const ATTRIBUTE_NAME = 'Type';
 
     #[Type('Array<int>')]
diff --git a/src/Throws.php b/src/Throws.php
@@ -0,0 +1,20 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PhpStaticAnalysis\Attributes;
+
+use Attribute;
+
+#[Attribute(
+    Attribute::TARGET_METHOD |
+    Attribute::TARGET_FUNCTION |
+    Attribute::IS_REPEATABLE
+)]
+final class Throws
+{
+    public function __construct(
+        string ...$exceptions
+    ) {
+    }
+}
diff --git a/tests/MixinTest.php b/tests/MixinTest.php
@@ -17,10 +17,10 @@ class C
 {
 }
 
-#[Mixin('A')]
+#[Mixin(A::class)]
 #[Mixin(
-    'B',
-    'C',
+    B::class,
+    C::class,
 )]
 class MixinTest extends TestCase
 {
diff --git a/tests/RequireExtendsTest.php b/tests/RequireExtendsTest.php
@@ -33,7 +33,7 @@ class RequireParentClass
 {
 }
 
-#[RequireExtends('RequireParentClass')]
+#[RequireExtends(RequireParentClass::class)]
 trait RequireMyTrait
 {
 }
diff --git a/tests/RequireImplementsTest.php b/tests/RequireImplementsTest.php
@@ -35,10 +35,10 @@ public static function getRequireImplementssFromReflection(
     }
 }
 
-#[RequireImplements('RequireTestInterface')]
+#[RequireImplements(RequireTestInterface::class)]
 #[RequireImplements(
-    'RequireTestInterface2',
-    'RequireTestInterface3'
+    RequireTestInterface2::class,
+    RequireTestInterface3::class
 )]
 trait RequireInterfaceTrait
 {
diff --git a/tests/ThrowsTest.php b/tests/ThrowsTest.php
@@ -0,0 +1,102 @@
+<?php
+
+declare(strict_types=1);
+
+use PhpStaticAnalysis\Attributes\Throws;
+use PHPUnit\Framework\TestCase;
+
+class ThrowsTest extends TestCase
+{
+    public function testMethodThrows(): void
+    {
+        $this->assertEquals(['Exception'], $this->methodThrows());
+    }
+
+    public function testInvalidTypeMethodThrows(): void
+    {
+        $errorThrown = false;
+        try {
+            $this->invalidTypeMethodThrows();
+        } catch (TypeError) {
+            $errorThrown = true;
+        }
+        $this->assertTrue($errorThrown);
+    }
+
+    public function testSeveralMethodThrows(): void
+    {
+        $this->assertEquals([
+            'Exception',
+            'Exception'
+        ], $this->severalMethodThrowss());
+    }
+
+    public function testMultipleMethodThrows(): void
+    {
+        $this->assertEquals([
+            'Exception',
+            'Exception'
+        ], $this->multipleMethodThrowss());
+    }
+
+    public function testFunctionThrows(): void
+    {
+        $this->assertEquals(['Exception'], functionThrows());
+    }
+
+    #[Throws(Exception::class)]
+    private function methodThrows(): array
+    {
+        return $this->getThrows(__FUNCTION__);
+    }
+
+    #[Throws(0)]
+    private function invalidTypeMethodThrows(): array
+    {
+        return $this->getThrows(__FUNCTION__);
+    }
+
+    #[Throws(
+        Exception::class,
+        Exception::class,
+    )]
+    private function severalMethodThrowss(): array
+    {
+        return $this->getThrows(__FUNCTION__);
+    }
+
+    #[Throws(Exception::class)]
+    #[Throws(Exception::class)]
+    private function multipleMethodThrowss(): array
+    {
+        return $this->getThrows(__FUNCTION__);
+    }
+
+    private function getThrows(string $functionName): array
+    {
+        $reflection = new ReflectionMethod($this, $functionName);
+        return self::getThrowsFromReflection($reflection);
+    }
+
+    public static function getThrowsFromReflection(
+        ReflectionMethod | ReflectionFunction $reflection
+    ): array {
+        $attributes = $reflection->getAttributes();
+        $throwss = [];
+        foreach ($attributes as $attribute) {
+            if ($attribute->getName() === Throws::class) {
+                $attribute->newInstance();
+                $throwss = array_merge($throwss, $attribute->getArguments());
+            }
+        }
+
+        return $throwss;
+    }
+}
+
+#[Throws(Exception::class)]
+function functionThrows(): array
+{
+    $reflection = new ReflectionFunction(__FUNCTION__);
+    return ThrowsTest::getThrowsFromReflection($reflection);
+}

Original file line number	Diff line number	Diff line change
`@@ -17,7 +17,7 @@ class ImpureExample`
`17`	`17`	`{`
`18`	`18`	`public static int $i = 0;`
`19`	`19`
`20`		`- #[Impure]`
	`20`	`+ #[Impure] // this function is impure`
`21`	`21`	`public static function addCumulative(int $left) : int`
`22`	`22`	`{`
`23`	`23`	`self::$i += $left;`
Original file line number	Diff line number	Diff line change
`@@ -17,7 +17,7 @@ use PhpStaticAnalysis\Attributes\IsReadOnly;`
`17`	`17`
`18`	`18`	`class IsReadOnlyExample`
`19`	`19`	`{`
`20`		`- #[IsReadOnly]`
	`20`	`+ #[IsReadOnly] // this property cannot be written to`
`21`	`21`	`public string $name;`
`22`	`22`
`23`	`23`	`...`
Original file line number	Diff line number	Diff line change
`@@ -24,7 +24,7 @@ class A`
`24`	`24`	`}`
`25`	`25`	`}`
`26`	`26`
`27`		`- #[Mixin('A')]`
	`27`	`+ #[Mixin(A::class)] // this class proxies A`
`28`	`28`	`class B`
`29`	`29`	`{`
`30`	`30`	`public function doB(): void`
Original file line number	Diff line number	Diff line change
`@@ -15,7 +15,7 @@ use PhpStaticAnalysis\Attributes\Pure;`
`15`	`15`
`16`	`16`	`class PureExample`
`17`	`17`	`{`
`18`		`- #[Pure]`
	`18`	`+ #[Pure] // this function is pure`
`19`	`19`	`public static function add(int $left, int $right) : int`
`20`	`20`	`{`
`21`	`21`	`return $left + $right;`
Original file line number	Diff line number	Diff line change
`@@ -18,7 +18,7 @@ use PhpStaticAnalysis\Attributes\RequireExtends;`
`18`	`18`	`abstract class Parent {`
`19`	`19`	`}`
`20`	`20`
`21`		`-#[RequireExtends('ParentClass')]`
	`21`	`+#[RequireExtends(Parent::class)] // needs to extend this class`
`22`	`22`	`trait myTrait {`
`23`	`23`	`}`
`24`	`24`