Add SelfOut attribute

README.md

@@ -110,6 +110,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`        |
 | [TemplateCovariant](https://github.com/php-static-analysis/attributes/blob/main/doc/TemplateCovariant.md)         | `@template-covariant`     |
 | [TemplateExtends](https://github.com/php-static-analysis/attributes/blob/main/doc/TemplateExtends.md)             | `@extends` `@template-extends` |

composer.json

@@ -26,8 +26,8 @@
     "require": {
         "php": ">=8.0",
         "ext-simplexml": "*",
-        "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",
         "vimeo/psalm": "^5"
     },
     "require-dev": {

tests/SelfOutAttributeTest.php

@@ -0,0 +1,24 @@
+<?php
+
+namespace test\PhpStaticAnalysis\PsalmPlugin;
+
+class SelfOutAttributeTest extends BaseAttributeTestCase
+{
+    public function testMethodSelfOutAttribute(): void
+    {
+        $errors = $this->analyzeTestFile('/data/SelfOut/MethodSelfOutAttribute.php');
+        $this->assertCount(0, $errors);
+    }
+
+    public function testInvalidMethodSelfOutAttribute(): void
+    {
+        $errors = $this->analyzeTestFile('/data/SelfOut/InvalidMethodSelfOutAttribute.php');
+
+        $expectedErrors = [
+            'Attribute SelfOut is not repeatable' => 15,
+            'Attribute SelfOut cannot be used on a property' => 20,
+        ];
+
+        $this->checkExpectedErrors($errors, $expectedErrors);
+    }
+}

tests/data/SelfOut/InvalidMethodSelfOutAttribute.php

@@ -0,0 +1,22 @@
+<?php
+
+namespace test\PhpStaticAnalysis\PsalmPlugin\data\SelfOut;
+
+use PhpStaticAnalysis\Attributes\Param;
+use PhpStaticAnalysis\Attributes\SelfOut;
+use PhpStaticAnalysis\Attributes\Template;
+
+#[Template('TValue')]
+class InvalidMethodSelfOutAttribute
+{
+    #[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\PsalmPlugin\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
+    {
+    }
+}