Add SelfOut attribute

Author: carlos-granados

Diff for: README.md

@@ -105,6 +105,7 @@ These are the available attributes and their corresponding PHPDoc annotations:
 | [PropertyRead](doc/PropertyRead.md)                   | `@property-read`                     |
 | [PropertyWrite](doc/PropertyWrite.md)                 | `@property-write`                    |
 | [Returns](doc/Returns.md)                             | `@return`                            |
+| [SelfOut](doc/SelfOut.md)                             | `@self-out` `@this-out`               |
 | [Template](doc/Template.md)                           | `@template`                          |
 | [TemplateContravariant](doc/TemplateContravariant.md) | `@template-contravariant`            |
 | [TemplateCovariant](doc/TemplateCovariant.md)         | `@template-covariant`                |

Diff for: doc/SelfOut.md

@@ -0,0 +1,31 @@
+# `SelfOut` Attribute
+
+This attribute is the equivalent of the `@self-out` or `@this-out` annotations. It can be used on class methods to specify the type of the current object after calling a method on it.
+
+## Arguments
+
+The attribute accepts a string which describes the type of the object after returning from the method. 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 `@self-out` annotation.
+
+## Example usage
+
+```php
+<?php
+
+use PhpStaticAnalysis\Attributes\Param;
+use PhpStaticAnalysis\Attributes\SelfOut;
+use PhpStaticAnalysis\Attributes\Template;
+
+#[Template('TValue')]
+class SelfOutExample
+{
+    #[Template('TItemValue')]
+    #[Param(item: 'TItemValue')]
+    #[SelfOut('self<TValue|TItemValue>')]
+	public function add($item): void
+	{
+	}	
+}
+
+```

Diff for: src/SelfOut.php

@@ -0,0 +1,18 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PhpStaticAnalysis\Attributes;
+
+use Attribute;
+
+#[Attribute(
+    Attribute::TARGET_METHOD
+)]
+final class SelfOut
+{
+    public function __construct(
+        string $type
+    ) {
+    }
+}

Diff for: tests/SelfOutTest.php

@@ -0,0 +1,92 @@
+<?php
+
+declare(strict_types=1);
+
+use PhpStaticAnalysis\Attributes\SelfOut;
+use PHPUnit\Framework\TestCase;
+
+class SelfOutTest extends TestCase
+{
+    public function testMethodSelfOut(): void
+    {
+        $this->assertEquals('self<T>', $this->methodSelfOut());
+    }
+
+    public function testMethodSelfOutArray(): void
+    {
+        $this->assertEquals(['self<T>'], $this->methodSelfOutArray());
+    }
+
+    public function testInvalidTypeMethodSelfOut(): void
+    {
+        $errorThrown = false;
+        try {
+            $this->invalidTypeMethodSelfOut();
+        } catch (TypeError) {
+            $errorThrown = true;
+        }
+        $this->assertTrue($errorThrown);
+    }
+
+    public function testMethodSelfOutWithTooManyParameters(): void
+    {
+        $this->assertEquals('self<T>', $this->methodSelfOutWithTooManyParameters());
+    }
+
+    public function testMultipleMethodSelfOut(): void
+    {
+        $errorThrown = false;
+        try {
+            $this->multipleMethodSelfOut();
+        } catch (Error) {
+            $errorThrown = true;
+        }
+        $this->assertTrue($errorThrown);
+    }
+
+    #[SelfOut('self<T>')]
+    private function methodSelfOut(): string
+    {
+        return $this->getSelfOut(__FUNCTION__);
+    }
+
+    #[SelfOut('self<T>')]
+    private function methodSelfOutArray(): array
+    {
+        return [$this->getSelfOut(__FUNCTION__)];
+    }
+
+    #[SelfOut(0)]
+    private function invalidTypeMethodSelfOut(): string
+    {
+        return $this->getSelfOut(__FUNCTION__);
+    }
+
+    #[SelfOut('self<T>', 'string')]
+    private function methodSelfOutWithTooManyParameters(): string
+    {
+        return $this->getSelfOut(__FUNCTION__);
+    }
+
+    #[SelfOut('self<T>')]
+    #[SelfOut('self<T>')]
+    private function multipleMethodSelfOut(): string
+    {
+        return $this->getSelfOut(__FUNCTION__);
+    }
+
+    private function getSelfOut(string $methodName): string
+    {
+        $reflection = new ReflectionMethod($this, $methodName);
+        $attributes = $reflection->getAttributes();
+        $selfOut = '';
+        foreach ($attributes as $attribute) {
+            if ($attribute->getName() === SelfOut::class) {
+                $attribute->newInstance();
+                $selfOut = $attribute->getArguments()[0];
+            }
+        }
+
+        return $selfOut;
+    }
+}