From 99c1313a3060bfaf27e59bfd379077070732d5f1 Mon Sep 17 00:00:00 2001
From: Carlos Granados <barel.barelon@gmail.com>
Date: Fri, 23 Feb 2024 16:39:05 +0100
Subject: [PATCH] Add ParamOut attribute

---
 README.md                                     |   5 +-
 composer.json                                 |   2 +-
 ...tic-analysis-annotations-to-attributes.php |   2 +
 src/AnnotationsToAttributesRector.php         |   6 +-
 ...ToAttributesWithParamOnParamRectorTest.php |   1 +
 tests/Fixture/ParamOutAttributeTest.php.inc   | 163 ++++++++++++++++++
 ...amOutAttributeTestWithParamOnParam.php.inc | 149 ++++++++++++++++
 7 files changed, 324 insertions(+), 4 deletions(-)
 create mode 100644 tests/Fixture/ParamOutAttributeTest.php.inc
 create mode 100644 tests/SpecialFixture/ParamOutAttributeTestWithParamOnParam.php.inc

diff --git a/README.md b/README.md
index 1d2f8bd..d29e632 100644
--- a/README.md
+++ b/README.md
@@ -118,6 +118,7 @@ These are the available attributes and their corresponding PHPDoc annotations:
 | [Method](https://github.com/php-static-analysis/attributes/blob/main/doc/Method.md)                               | `@method`                 |
 | [Mixin](https://github.com/php-static-analysis/attributes/blob/main/doc/Mixin.md)                                 | `@mixin`                  |
 | [Param](https://github.com/php-static-analysis/attributes/blob/main/doc/Param.md)                 | `@param`           |
+| [ParamOut](https://github.com/php-static-analysis/attributes/blob/main/doc/ParamOut.md)                           | `@param-out`                         |
 | [Property](https://github.com/php-static-analysis/attributes/blob/main/doc/Property.md)           | `@property` `@var` |
 | [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`  |
@@ -130,9 +131,9 @@ These are the available attributes and their corresponding PHPDoc annotations:
 | [TemplateUse](https://github.com/php-static-analysis/attributes/blob/main/doc/TemplateUse.md)             | `@use` `@template-use` |
 | [Type](https://github.com/php-static-analysis/attributes/blob/main/doc/Type.md)                   | `@var` `@return`   |
 
-### Location of Param attributes
+### Location of Param and ParamOut attributes
 
-By default `Param` attributes are added on the method/function where the `@param` annotation was located. It is possible to instead add them on the corresponding parameter in the function. To activate this option, add this code to your configuration:
+By default `Param` and `ParamOut `attributes are added on the method/function where the `@param` or `@param-out` annotation was located. It is possible to instead add them on the corresponding parameter in the function. To activate this option, add this code to your configuration:
 
 ```php
 use PhpStaticAnalysis\RectorRule\AnnotationsToAttributesRector;
diff --git a/composer.json b/composer.json
index c960a5d..921b0f1 100644
--- a/composer.json
+++ b/composer.json
@@ -28,7 +28,7 @@
     "require": {
         "php": ">=8.0",
         "cweagans/composer-patches": "^1.7",
-        "php-static-analysis/attributes": "^0.1.11 || dev-main",
+        "php-static-analysis/attributes": "^0.1.12 || dev-main",
         "rector/rector": "^0.19 || ^1.0"
     },
     "require-dev": {
diff --git a/config/sets/php-static-analysis-annotations-to-attributes.php b/config/sets/php-static-analysis-annotations-to-attributes.php
index d58ddd8..62a8f9a 100644
--- a/config/sets/php-static-analysis-annotations-to-attributes.php
+++ b/config/sets/php-static-analysis-annotations-to-attributes.php
@@ -6,6 +6,7 @@
 use PhpStaticAnalysis\Attributes\Internal;
 use PhpStaticAnalysis\Attributes\Method;
 use PhpStaticAnalysis\Attributes\Mixin;
+use PhpStaticAnalysis\Attributes\ParamOut;
 use PhpStaticAnalysis\Attributes\PropertyRead;
 use PhpStaticAnalysis\Attributes\PropertyWrite;
 use PhpStaticAnalysis\Attributes\TemplateContravariant;
@@ -34,6 +35,7 @@
             new AnnotationToAttribute('method', Method::class),
             new AnnotationToAttribute('mixin', Mixin::class),
             new AnnotationToAttribute('param', Param::class),
+            new AnnotationToAttribute('param_out', ParamOut::class),
             new AnnotationToAttribute('property', Property::class),
             new AnnotationToAttribute('property_read', PropertyRead::class),
             new AnnotationToAttribute('property_write', PropertyWrite::class),
diff --git a/src/AnnotationsToAttributesRector.php b/src/AnnotationsToAttributesRector.php
index b284eca..7acd6cd 100644
--- a/src/AnnotationsToAttributesRector.php
+++ b/src/AnnotationsToAttributesRector.php
@@ -17,6 +17,7 @@
 use PHPStan\PhpDocParser\Ast\PhpDoc\ImplementsTagValueNode;
 use PHPStan\PhpDocParser\Ast\PhpDoc\MethodTagValueNode;
 use PHPStan\PhpDocParser\Ast\PhpDoc\MixinTagValueNode;
+use PHPStan\PhpDocParser\Ast\PhpDoc\ParamOutTagValueNode;
 use PHPStan\PhpDocParser\Ast\PhpDoc\ParamTagValueNode;
 use PHPStan\PhpDocParser\Ast\PhpDoc\PhpDocTagNode;
 use PHPStan\PhpDocParser\Ast\PhpDoc\PropertyTagValueNode;
@@ -26,6 +27,7 @@
 use PHPStan\PhpDocParser\Ast\PhpDoc\VarTagValueNode;
 use PHPStan\PhpDocParser\Ast\Type\IdentifierTypeNode;
 use PhpStaticAnalysis\Attributes\Param;
+use PhpStaticAnalysis\Attributes\ParamOut;
 use PhpStaticAnalysis\Attributes\Property;
 use PhpStaticAnalysis\Attributes\Returns;
 use PhpStaticAnalysis\Attributes\Type;
@@ -184,7 +186,8 @@ public function refactor(Node $node): ?Node
             ($node instanceof Stmt\ClassMethod || $node instanceof Stmt\Function_)) {
             foreach ($attributeGroups as $attrKey => $attributeGroup) {
                 foreach ($attributeGroup->attrs as $key => $attribute) {
-                    if ((string)$attribute->name === Param::class) {
+                    $attributeName = (string)$attribute->name;
+                    if ($attributeName === Param::class || $attributeName == ParamOut::class) {
                         $args = $attribute->args;
                         if (isset($args[0])) {
                             $arg = $args[0];
@@ -261,6 +264,7 @@ private function processAnnotations(PhpDocInfo $phpDocInfo): array
                         new Node\Arg(new Scalar\String_($methodSignature))
                     ];
                     break;
+                case $tagValueNode instanceof ParamOutTagValueNode:
                 case $tagValueNode instanceof ParamTagValueNode:
                     $args = [
                         new Node\Arg(
diff --git a/tests/AnnotationsToAttributesWithParamOnParamRectorTest.php b/tests/AnnotationsToAttributesWithParamOnParamRectorTest.php
index 8bf177b..05e7c02 100644
--- a/tests/AnnotationsToAttributesWithParamOnParamRectorTest.php
+++ b/tests/AnnotationsToAttributesWithParamOnParamRectorTest.php
@@ -20,6 +20,7 @@ public function test(string $filePath): void
     public static function provideData(): Iterator
     {
         yield [__DIR__ . '/SpecialFixture/ParamAttributeTestWithParamOnParam.php.inc'];
+        yield [__DIR__ . '/SpecialFixture/ParamOutAttributeTestWithParamOnParam.php.inc'];
     }
 
     public function provideConfigFilePath(): string
diff --git a/tests/Fixture/ParamOutAttributeTest.php.inc b/tests/Fixture/ParamOutAttributeTest.php.inc
new file mode 100644
index 0000000..a7ade9c
--- /dev/null
+++ b/tests/Fixture/ParamOutAttributeTest.php.inc
@@ -0,0 +1,163 @@
+<?php
+
+namespace test\PhpStaticAnalysis\RectorRule\Fixture;
+
+use PhpStaticAnalysis\Attributes\ParamOut;
+use PhpStaticAnalysis\Attributes\Returns;
+
+class ParamOutAttributeTest
+{
+    /**
+     * @param-out string $name
+     */
+    public function setName(&$name)
+    {
+        $name = '';
+    }
+
+    /**
+     * @codeCoverageIgnore
+     * @param-out string $name
+     */
+    public function setMoreNames(&$name)
+    {
+        $name = '';
+    }
+
+    /**
+     * @param-out string $name
+     */
+    #[Returns('void')]
+    public function setAnotherName(&$name)
+    {
+        $name = '';
+    }
+
+    /**
+     * @param-out string $name1
+     * @param-out string $name2
+     */
+    public function setTwoNames(&$name1, &$name2)
+    {
+        $name1 = '';
+        $name2 = '';
+    }
+
+    /**
+     * @param-out string $name2
+     */
+    #[ParamOut(name1: 'string')]
+    public function setTwoMoreNames(&$name1, &$name2)
+    {
+        $name1 = '';
+        $name2 = '';
+    }
+
+    /**
+     * @param-out string $name the name of the user
+     */
+    public function setUserName(&$name)
+    {
+        $name = '';
+    }
+
+    /**
+     * @psalm-param-out string $name
+     */
+    public function setPsalmName(&$name)
+    {
+        $name = '';
+    }
+
+    /**
+     * @phpstan-param-out string $name
+     */
+    public function setPHPStanName(&$name)
+    {
+        $name = '';
+    }
+}
+
+/**
+ * @param-out string $name
+ */
+function setName(&$name)
+{
+    $name = '';
+}
+
+?>
+-----
+<?php
+
+namespace test\PhpStaticAnalysis\RectorRule\Fixture;
+
+use PhpStaticAnalysis\Attributes\ParamOut;
+use PhpStaticAnalysis\Attributes\Returns;
+
+class ParamOutAttributeTest
+{
+    #[\PhpStaticAnalysis\Attributes\ParamOut(name: 'string')]
+    public function setName(&$name)
+    {
+        $name = '';
+    }
+
+    /**
+     * @codeCoverageIgnore
+     */
+    #[\PhpStaticAnalysis\Attributes\ParamOut(name: 'string')]
+    public function setMoreNames(&$name)
+    {
+        $name = '';
+    }
+
+    #[Returns('void')]
+    #[\PhpStaticAnalysis\Attributes\ParamOut(name: 'string')]
+    public function setAnotherName(&$name)
+    {
+        $name = '';
+    }
+
+    #[\PhpStaticAnalysis\Attributes\ParamOut(name1: 'string')]
+    #[\PhpStaticAnalysis\Attributes\ParamOut(name2: 'string')]
+    public function setTwoNames(&$name1, &$name2)
+    {
+        $name1 = '';
+        $name2 = '';
+    }
+
+    #[ParamOut(name1: 'string')]
+    #[\PhpStaticAnalysis\Attributes\ParamOut(name2: 'string')]
+    public function setTwoMoreNames(&$name1, &$name2)
+    {
+        $name1 = '';
+        $name2 = '';
+    }
+
+    #[\PhpStaticAnalysis\Attributes\ParamOut(name: 'string')] // the name of the user
+    public function setUserName(&$name)
+    {
+        $name = '';
+    }
+
+    #[\PhpStaticAnalysis\Attributes\ParamOut(name: 'string')]
+    public function setPsalmName(&$name)
+    {
+        $name = '';
+    }
+
+    #[\PhpStaticAnalysis\Attributes\ParamOut(name: 'string')]
+    public function setPHPStanName(&$name)
+    {
+        $name = '';
+    }
+}
+
+#[\PhpStaticAnalysis\Attributes\ParamOut(name: 'string')]
+function setName(&$name)
+{
+    $name = '';
+}
+
+?>
diff --git a/tests/SpecialFixture/ParamOutAttributeTestWithParamOnParam.php.inc b/tests/SpecialFixture/ParamOutAttributeTestWithParamOnParam.php.inc
new file mode 100644
index 0000000..ce82e87
--- /dev/null
+++ b/tests/SpecialFixture/ParamOutAttributeTestWithParamOnParam.php.inc
@@ -0,0 +1,149 @@
+<?php
+
+namespace test\PhpStaticAnalysis\RectorRule\SpecialFixture;
+
+use PhpStaticAnalysis\Attributes\ParamOut;
+use PhpStaticAnalysis\Attributes\Returns;
+
+class ParamOutAttributeTestWithParamOnParam
+{
+    /**
+     * @param-out string $name
+     */
+    public function setName(&$name)
+    {
+        $name = '';
+    }
+
+    /**
+     * @codeCoverageIgnore
+     * @param-out string $name
+     */
+    public function setMoreNames(&$name)
+    {
+        $name = '';
+    }
+
+    /**
+     * @param-out string $name
+     */
+    #[Returns('string')]
+    public function setAnotherName(&$name)
+    {
+        $name = '';
+    }
+
+    /**
+     * @param-out string $name1
+     * @param-out string $name2
+     */
+    public function setTwoNames(&$name1, &$name2)
+    {
+        $name1 = '';
+        $name2 = '';
+    }
+
+    /**
+     * @param-out string $name2
+     */
+    #[ParamOut(name1: 'string')]
+    public function setTwoMoreNames(&$name1, &$name2)
+    {
+        $name1 = '';
+        $name2 = '';
+    }
+
+    /**
+     * @psalm-param-out string $name
+     */
+    public function setPsalmName(&$name)
+    {
+        $name = '';
+    }
+
+    /**
+     * @phpstan-param-out string $name
+     */
+    public function setPHPStanName(&$name)
+    {
+        $name = '';
+    }
+}
+
+/**
+ * @param-out string $name
+ */
+function setName(&$name)
+{
+    $name = '';
+}
+
+?>
+-----
+<?php
+
+namespace test\PhpStaticAnalysis\RectorRule\SpecialFixture;
+
+use PhpStaticAnalysis\Attributes\ParamOut;
+use PhpStaticAnalysis\Attributes\Returns;
+
+class ParamOutAttributeTestWithParamOnParam
+{
+    public function setName(#[\PhpStaticAnalysis\Attributes\ParamOut('string')]
+    &$name)
+    {
+        $name = '';
+    }
+
+    /**
+     * @codeCoverageIgnore
+     */
+    public function setMoreNames(#[\PhpStaticAnalysis\Attributes\ParamOut('string')]
+    &$name)
+    {
+        $name = '';
+    }
+
+    #[Returns('string')]
+    public function setAnotherName(#[\PhpStaticAnalysis\Attributes\ParamOut('string')]
+    &$name)
+    {
+        $name = '';
+    }
+
+    public function setTwoNames(#[\PhpStaticAnalysis\Attributes\ParamOut('string')]
+    &$name1, #[\PhpStaticAnalysis\Attributes\ParamOut('string')]
+    &$name2)
+    {
+        $name1 = '';
+        $name2 = '';
+    }
+
+    #[ParamOut(name1: 'string')]
+    public function setTwoMoreNames(&$name1, #[\PhpStaticAnalysis\Attributes\ParamOut('string')]
+    &$name2)
+    {
+        $name1 = '';
+        $name2 = '';
+    }
+
+    public function setPsalmName(#[\PhpStaticAnalysis\Attributes\ParamOut('string')]
+    &$name)
+    {
+        $name = '';
+    }
+
+    public function setPHPStanName(#[\PhpStaticAnalysis\Attributes\ParamOut('string')]
+    &$name)
+    {
+        $name = '';
+    }
+}
+
+function setName(#[\PhpStaticAnalysis\Attributes\ParamOut('string')]
+&$name)
+{
+    $name = '';
+}
+
+?>