Add Throws attribute

Author: carlos-granados

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`                     |
 

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;

doc/IsReadOnly.md

@@ -17,7 +17,7 @@ use PhpStaticAnalysis\Attributes\IsReadOnly;
 
 class IsReadOnlyExample
 {
-    #[IsReadOnly]
+    #[IsReadOnly] // this property cannot be written to
     public string $name;
 
     ...

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()',

doc/Mixin.md

@@ -24,7 +24,7 @@ class A
     }
 }
 
- #[Mixin('A')]
+ #[Mixin(A::class)] // this class proxies A
 class B
 {
     public function doB(): void

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[]',

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[]',

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[]',

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;

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 {
 }
 

doc/RequireImplements.md

@@ -23,7 +23,7 @@ interface RequireInterface
 {
 }
 
-#[RequireImplements('RequireInterface')]
+#[RequireImplements(RequireInterface::class)] //needs to implement this interface
 trait MyTrait
 {
 }

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'];

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
 	{
 	}	

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 {}
 ```

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 {}
 ```

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;
 }

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();
+    }
+}
+```

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>')]

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
+    ) {
+    }
+}

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
 {

tests/RequireExtendsTest.php

@@ -33,7 +33,7 @@ class RequireParentClass
 {
 }
 
-#[RequireExtends('RequireParentClass')]
+#[RequireExtends(RequireParentClass::class)]
 trait RequireMyTrait
 {
 }

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
 {

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);
+}