Add ParamOut attribute

Author: carlos-granados

composer.json

@@ -25,7 +25,7 @@
     "require": {
         "php": ">=8.0",
         "nikic/php-parser": "^4 || ^5",
-        "php-static-analysis/attributes": "^0.1.11 || dev-main"
+        "php-static-analysis/attributes": "^0.1.12 || dev-main"
     },
     "require-dev": {
         "php-static-analysis/phpstan-extension": "dev-main",

src/AttributeNodeVisitor.php

@@ -17,6 +17,7 @@
 use PhpStaticAnalysis\Attributes\Method;
 use PhpStaticAnalysis\Attributes\Mixin;
 use PhpStaticAnalysis\Attributes\Param;
+use PhpStaticAnalysis\Attributes\ParamOut;
 use PhpStaticAnalysis\Attributes\Property;
 use PhpStaticAnalysis\Attributes\PropertyRead;
 use PhpStaticAnalysis\Attributes\PropertyWrite;
@@ -74,6 +75,7 @@ class AttributeNodeVisitor extends NodeVisitorAbstract
             Deprecated::class,
             Internal::class,
             Param::class,
+            ParamOut::class,
             Returns::class,
             Template::class,
             Type::class,
@@ -82,6 +84,7 @@ class AttributeNodeVisitor extends NodeVisitorAbstract
             Deprecated::class,
             Internal::class,
             Param::class,
+            ParamOut::class,
             Returns::class,
             Template::class,
             Type::class,
@@ -126,6 +129,7 @@ class AttributeNodeVisitor extends NodeVisitorAbstract
         'Method' => Method::class,
         'Mixin' => Mixin::class,
         'Param' => Param::class,
+        'ParamOut' => ParamOut::class,
         'Property' => Property::class,
         'PropertyRead' => PropertyRead::class,
         'PropertyWrite' => PropertyWrite::class,
@@ -158,6 +162,9 @@ class AttributeNodeVisitor extends NodeVisitorAbstract
         Param::class => [
             'all' => 'param',
         ],
+        ParamOut::class => [
+            'all' => 'param-out',
+        ],
         Property::class => [
             Stmt\Class_::class => 'property',
             Stmt\Property::class => 'var',
@@ -216,6 +223,9 @@ class AttributeNodeVisitor extends NodeVisitorAbstract
         Param::class => [
             'all' => self::ARGS_MANY_WITH_NAME,
         ],
+        ParamOut::class => [
+            'all' => self::ARGS_MANY_WITH_NAME,
+        ],
         Property::class => [
             Stmt\Class_::class => self::ARGS_MANY_WITH_NAME,
             Stmt\Property::class => self::ARGS_ONE,
@@ -430,7 +440,7 @@ private function getParamTagsFromParams(Stmt\ClassMethod|Stmt\Function_ $node):
                 foreach ($attributes as $attribute) {
                     $attributeName = $attribute->name->toString();
                     $attributeName = self::SHORT_NAME_TO_FQN[$attributeName] ?? $attributeName;
-                    if ($attributeName === Param::class) {
+                    if ($attributeName === Param::class || $attributeName === ParamOut::class) {
                         $args = $attribute->args;
                         $tagCreated = false;
                         if (isset($args[0])) {

tests/ParamOutAttributeNodeVisitorTest.php

@@ -0,0 +1,75 @@
+<?php
+
+namespace test\PhpStaticAnalysis\NodeVisitor;
+
+use PhpParser\Node;
+use PhpParser\Node\Attribute;
+use PhpParser\Node\AttributeGroup;
+use PhpParser\Node\Identifier;
+use PhpParser\Node\Name\FullyQualified;
+use PhpStaticAnalysis\Attributes\ParamOut;
+
+class ParamOutAttributeNodeVisitorTest extends AttributeNodeVisitorTestBase
+{
+    public function testAddsParamOutPHPDoc(): void
+    {
+        $node = new Node\Stmt\ClassMethod('Test');
+        $this->addParamOutAttributesToNode($node);
+        $this->nodeVisitor->enterNode($node);
+        $docText = $this->getDocText($node);
+        $this->assertEquals("/**\n * @param-out string \$param\n */", $docText);
+    }
+
+    public function testAddsSeveralParamOutPHPDocs(): void
+    {
+        $node = new Node\Stmt\ClassMethod('Test');
+        $this->addParamOutAttributesToNode($node, 2);
+        $this->nodeVisitor->enterNode($node);
+        $docText = $this->getDocText($node);
+        $this->assertEquals("/**\n * @param-out string \$param\n * @param-out string \$param\n */", $docText);
+    }
+
+    public function testAddsMultipleParamOutPHPDocs(): void
+    {
+        $node = new Node\Stmt\ClassMethod('Test');
+        $this->addParamOutAttributesToNode($node);
+        $this->addParamOutAttributesToNode($node);
+        $this->nodeVisitor->enterNode($node);
+        $docText = $this->getDocText($node);
+        $this->assertEquals("/**\n * @param-out string \$param\n * @param-out string \$param\n */", $docText);
+    }
+
+    public function testAddsParamOutPHPDocToParam(): void
+    {
+        $node = new Node\Stmt\ClassMethod('Test');
+        $this->addParamOutAttributeToParamNode($node);
+        $this->nodeVisitor->enterNode($node);
+        $docText = $this->getDocText($node);
+        $this->assertEquals("/**\n * @param-out string \$param\n */", $docText);
+    }
+
+    private function addParamOutAttributesToNode(Node\Stmt\ClassMethod $node, int $num = 1): void
+    {
+        $name = new Identifier('param');
+        $value = new Node\Scalar\String_('string');
+        $args = [];
+        for ($i = 0; $i < $num; $i++) {
+            $args[] = new Node\Arg($value, name: $name);
+        }
+        $attributeName = new FullyQualified(ParamOut::class);
+        $attribute = new Attribute($attributeName, $args);
+        $node->attrGroups = array_merge($node->attrGroups, [new AttributeGroup([$attribute])]);
+    }
+
+    private function addParamOutAttributeToParamNode(Node\Stmt\ClassMethod $node): void
+    {
+        $var = new Node\Expr\Variable('param');
+        $parameter = new Node\Param($var);
+        $value = new Node\Scalar\String_('string');
+        $args = [new Node\Arg($value)];
+        $attributeName = new FullyQualified(ParamOut::class);
+        $attribute = new Attribute($attributeName, $args);
+        $parameter->attrGroups = array_merge($node->attrGroups, [new AttributeGroup([$attribute])]);
+        $node->params = [$parameter];
+    }
+}