Add SelfOut attribute

Author: carlos-granados

README.md

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

composer.json

@@ -24,8 +24,8 @@
     "prefer-stable": true,
     "require": {
         "php": ">=8.0",
-        "php-static-analysis/attributes": "^0.1.12 || dev-main",
-        "php-static-analysis/node-visitor": "^0.1.12 || dev-main",
+        "php-static-analysis/attributes": "^0.1.13 || dev-main",
+        "php-static-analysis/node-visitor": "^0.1.13 || dev-main",
         "phpstan/phpstan": "^1.8"
     },
     "require-dev": {

tests/SelfOutAttributeTest.php

@@ -0,0 +1,26 @@
+<?php
+
+namespace test\PhpStaticAnalysis\PHPStanExtension;
+
+class SelfOutAttributeTest extends BaseAttributeTestCase
+{
+    public function testMethodSelfOutAttribute(): void
+    {
+        $errors = $this->analyse(__DIR__ . '/data/SelfOut/MethodSelfOutAttribute.php');
+        $this->assertCount(0, $errors);
+    }
+
+    public function testInvalidMethodSelfOutAttribute(): void
+    {
+        $errors = $this->analyse(__DIR__ . '/data/SelfOut/InvalidMethodSelfOutAttribute.php');
+
+        $expectedErrors = [
+            'PHPDoc tag @phpstan-self-out has invalid value (): Unexpected token "\n ", expected type at offset 75' => 12,
+            'Parameter #1 $type of attribute class PhpStaticAnalysis\Attributes\SelfOut constructor expects string, int given.' => 14,
+            'Attribute class PhpStaticAnalysis\Attributes\SelfOut is not repeatable but is already present above the method.' => 22,
+            'Attribute class PhpStaticAnalysis\Attributes\SelfOut does not have the property target.' => 27,
+        ];
+
+        $this->checkExpectedErrors($errors, $expectedErrors);
+    }
+}

tests/data/SelfOut/InvalidMethodSelfOutAttribute.php

@@ -0,0 +1,29 @@
+<?php
+
+namespace test\PhpStaticAnalysis\PHPStanExtension\data\SelfOut;
+
+use PhpStaticAnalysis\Attributes\Param;
+use PhpStaticAnalysis\Attributes\SelfOut;
+use PhpStaticAnalysis\Attributes\Template;
+
+#[Template('TValue')]
+class InvalidMethodSelfOutAttribute
+{
+    #[Template('TItemValue')]
+    #[Param(item: 'TItemValue')]
+    #[SelfOut(0)]
+    public function add($item): void
+    {
+    }
+
+    #[Template('TItemValue')]
+    #[Param(item: 'TItemValue')]
+    #[SelfOut('self<TValue|TItemValue>')]
+    #[SelfOut('self<TValue|TItemValue>')]
+    public function addMore($item): void
+    {
+    }
+
+    #[SelfOut('self<TValue|TItemValue>')]
+    public string $property;
+}

tests/data/SelfOut/MethodSelfOutAttribute.php

@@ -0,0 +1,47 @@
+<?php
+
+namespace test\PhpStaticAnalysis\PHPStanExtension\data\SelfOut;
+
+use PhpStaticAnalysis\Attributes\Param;
+use PhpStaticAnalysis\Attributes\SelfOut;
+use PhpStaticAnalysis\Attributes\Template;
+
+#[Template('TValue')]
+class MethodSelfOutAttribute
+{
+    #[Template('TItemValue')]
+    #[Param(item: 'TItemValue')]
+    #[SelfOut('self<TValue|TItemValue>')] // we specify the new type
+    public function add($item): void
+    {
+    }
+
+    /**
+     * @deprecated
+     */
+    #[Template('TItemValue')]
+    #[Param(item: 'TItemValue')]
+    #[SelfOut('self<TValue|TItemValue>')]
+    public function addMore($item): void
+    {
+    }
+
+    /**
+     * @self-out self<TValue>
+     */
+    #[Template('TItemValue')]
+    #[Param(item: 'TItemValue')]
+    #[SelfOut('self<TValue|TItemValue>')]
+    public function addEvenMore($item): void
+    {
+    }
+
+    /**
+     * @self-out self<TValue|TItemValue>
+     */
+    #[Template('TItemValue')]
+    #[Param(item: 'TItemValue')]
+    public function addMoreAndMore($item): void
+    {
+    }
+}