Use format-preserving printer from phpstan/phpdoc-parser

bench/phpdoc_info_printer_bench.php

@@ -0,0 +1,153 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * Benchmark for parsing and printing docblocks: PhpDocInfoFactory::createFromNode() and
+ * PhpDocInfoPrinter::printFormatPreserving().
+ *
+ * Measured per docblock:
+ *   - parse:          createFromNode(), incl. the node visitors run on every docblock
+ *   - print @return:  change the @return type, then print
+ *   - print add tag:  add a @throws tag, then print
+ *
+ * Run on both branches to compare:
+ *   php bench/phpdoc_info_printer_bench.php
+ *
+ * Reports CPU time (user+sys) per docblock in µs, median of REPEAT runs.
+ */
+
+use PhpParser\Comment\Doc;
+use PhpParser\Node\Stmt\ClassMethod;
+use PHPStan\PhpDocParser\Ast\PhpDoc\PhpDocTagNode;
+use PHPStan\PhpDocParser\Ast\PhpDoc\ReturnTagValueNode;
+use PHPStan\PhpDocParser\Ast\PhpDoc\ThrowsTagValueNode;
+use PHPStan\PhpDocParser\Ast\Type\IdentifierTypeNode;
+use Rector\BetterPhpDocParser\PhpDocInfo\PhpDocInfo;
+use Rector\BetterPhpDocParser\PhpDocInfo\PhpDocInfoFactory;
+use Rector\BetterPhpDocParser\Printer\PhpDocInfoPrinter;
+use Rector\DependencyInjection\LazyContainerFactory;
+
+require __DIR__ . '/../vendor/autoload.php';
+
+const ITERATIONS = 300;
+const REPEAT = 7;
+
+$createDocWithTags = static function (int $count): string {
+    $lines = ['/**', ' * Large docblock.', ' *'];
+    for ($i = 0; $i < $count; ++$i) {
+        $lines[] = sprintf(' * @param array<string, int|Foo%d>|null $param%d Description %d.', $i, $i, $i);
+    }
+
+    $lines[] = ' * @return array<int, string>';
+    $lines[] = ' */';
+
+    return implode("\n", $lines);
+};
+
+$docs = [
+    'simple' => "/**\n * @param int \$a\n * @return string\n */",
+    'generics' => "/**\n * @param array<string, list<int>> \$map\n * @param Collection<int, Foo>|null \$items\n * @return iterable<int, Foo>\n */",
+    'array shape' => "/**\n * @param array{id: int, name?: string, tags: list<string>} \$row\n * @return array{id: int, name?: string}\n */",
+    'callable' => "/**\n * @param callable(int, string): void \$cb\n * @param Closure(Foo \$foo, int ...\$rest): (int|null) \$fn\n * @return callable(): int\n */",
+    'description' => "/**\n * Fetches the records.\n *\n * This method reads all records\n * and returns them as a list.\n *\n * @param int \$limit Max number of rows. When it is 0,\n *                   all rows are returned.\n * @return list<Record>\n */",
+    'doctrine' => "/**\n * @ORM\\Column(type=\"string\", length=255, nullable=true)\n * @ORM\\ManyToOne(targetEntity=\"App\\Entity\\User\", inversedBy=\"posts\")\n * @return string\n */",
+    '10 tags' => $createDocWithTags(10),
+    '30 tags' => $createDocWithTags(30),
+    '60 tags' => $createDocWithTags(60),
+];
+
+$rectorConfig = (new LazyContainerFactory())->create();
+$rectorConfig->boot();
+
+$phpDocInfoFactory = $rectorConfig->make(PhpDocInfoFactory::class);
+$phpDocInfoPrinter = $rectorConfig->make(PhpDocInfoPrinter::class);
+
+// the factory caches every PhpDocInfo by node object id; clear it before each run to limit memory
+$phpDocInfosByObjectId = new ReflectionProperty(PhpDocInfoFactory::class, 'phpDocInfosByObjectId');
+
+$cpuSeconds = static function (): float {
+    $usage = getrusage();
+    return $usage['ru_utime.tv_sec'] + $usage['ru_utime.tv_usec'] / 1_000_000
+        + $usage['ru_stime.tv_sec'] + $usage['ru_stime.tv_usec'] / 1_000_000;
+};
+
+// a new node per docblock, as PhpDocInfoFactory caches by node
+$createPhpDocInfo = static function (string $doc) use ($phpDocInfoFactory): PhpDocInfo {
+    $classMethod = new ClassMethod('run');
+    $classMethod->setDocComment(new Doc($doc));
+
+    $phpDocInfo = $phpDocInfoFactory->createFromNode($classMethod);
+    assert($phpDocInfo instanceof PhpDocInfo);
+
+    return $phpDocInfo;
+};
+
+$change = static function (PhpDocInfo $phpDocInfo, string $case): void {
+    if ($case === 'print @return') {
+        $returnTagValueNode = $phpDocInfo->getReturnTagValue();
+        assert($returnTagValueNode instanceof ReturnTagValueNode);
+        $returnTagValueNode->type = new IdentifierTypeNode('Bar');
+        return;
+    }
+
+    $phpDocInfo->addPhpDocTagNode(
+        new PhpDocTagNode('@throws', new ThrowsTagValueNode(new IdentifierTypeNode('Foo'), ''))
+    );
+};
+
+/**
+ * @return float µs per docblock
+ */
+$measure = static function (string $doc, string $case) use (
+    $createPhpDocInfo,
+    $change,
+    $phpDocInfoPrinter,
+    $cpuSeconds,
+    $phpDocInfoFactory,
+    $phpDocInfosByObjectId
+): float {
+    $phpDocInfosByObjectId->setValue($phpDocInfoFactory, []);
+
+    $phpDocInfos = [];
+    for ($i = 0; $i < ITERATIONS; ++$i) {
+        $phpDocInfos[] = $case === 'parse' ? null : $createPhpDocInfo($doc);
+    }
+
+    if ($case !== 'parse') {
+        foreach ($phpDocInfos as $phpDocInfo) {
+            $change($phpDocInfo, $case);
+        }
+    }
+
+    $start = $cpuSeconds();
+    foreach ($phpDocInfos as $phpDocInfo) {
+        if ($phpDocInfo === null) {
+            $createPhpDocInfo($doc);
+        } else {
+            $phpDocInfoPrinter->printFormatPreserving($phpDocInfo);
+        }
+    }
+
+    return ($cpuSeconds() - $start) / ITERATIONS * 1_000_000;
+};
+
+printf("%-12s %10s %15s %15s\n", 'docblock', 'parse', 'print @return', 'print add tag');
+
+foreach ($docs as $name => $doc) {
+    $results = [];
+    foreach (['parse', 'print @return', 'print add tag'] as $case) {
+        // warmup
+        $measure($doc, $case);
+
+        $times = [];
+        for ($repeat = 0; $repeat < REPEAT; ++$repeat) {
+            $times[] = $measure($doc, $case);
+        }
+
+        sort($times);
+        $results[] = $times[intdiv(REPEAT, 2)];
+    }
+
+    printf("%-12s %10.1f %15.1f %15.1f\n", $name, ...$results);
+}

phpstan.neon

@@ -300,7 +300,6 @@ parameters:
             message: '#Function "property_exists\(\)" cannot be used/left in the code#'
             paths:
                 - src/NodeNameResolver/NodeNameResolver.php
-                - src/BetterPhpDocParser/PhpDocParser/BetterPhpDocParser.php
                 - src/BetterPhpDocParser/NodeDecorator/DoctrineAnnotationDecorator.php
 
         -

rules-tests/TypeDeclaration/Rector/Property/TypedPropertyFromStrictSetUpRector/Fixture/include_mock_doc.php.inc

@@ -27,7 +27,7 @@ use PHPUnit\Framework\TestCase;
 
 final class IncludeMockDoc extends TestCase
 {
-    /** @var (\PHPUnit\Framework\MockObject\MockObject & \DateTime) */
+    /** @var \PHPUnit\Framework\MockObject\MockObject&\DateTime */
     private \PHPUnit\Framework\MockObject\MockObject $value;
 
     public function setUp(): void

rules/DeadCode/PhpDoc/DeadParamTagValueNodeAnalyzer.php

@@ -11,8 +11,8 @@
 use PHPStan\PhpDocParser\Ast\PhpDoc\ParamTagValueNode;
 use PHPStan\PhpDocParser\Ast\Type\GenericTypeNode;
 use PHPStan\PhpDocParser\Ast\Type\IdentifierTypeNode;
+use PHPStan\PhpDocParser\Ast\Type\UnionTypeNode;
 use Rector\BetterPhpDocParser\PhpDocManipulator\PhpDocTypeChanger;
-use Rector\BetterPhpDocParser\ValueObject\Type\BracketsAwareUnionTypeNode;
 use Rector\DeadCode\PhpDoc\Guard\StandaloneTypeRemovalGuard;
 use Rector\DeadCode\PhpDoc\Guard\TemplateTypeRemovalGuard;
 use Rector\DeadCode\TypeNodeAnalyzer\GenericTypeNodeAnalyzer;
@@ -80,19 +80,19 @@ public function isDead(ParamTagValueNode $paramTagValueNode, FunctionLike $funct
             return false;
         }
 
-        if (! $paramTagValueNode->type instanceof BracketsAwareUnionTypeNode) {
+        if (! $paramTagValueNode->type instanceof UnionTypeNode) {
             return $this->standaloneTypeRemovalGuard->isLegal($paramTagValueNode->type, $param->type);
         }
 
-        return $this->isAllowedBracketAwareUnion($paramTagValueNode->type);
+        return $this->isAllowedUnion($paramTagValueNode->type);
     }
 
-    private function isAllowedBracketAwareUnion(BracketsAwareUnionTypeNode $bracketsAwareUnionTypeNode): bool
+    private function isAllowedUnion(UnionTypeNode $unionTypeNode): bool
     {
-        if ($this->mixedArrayTypeNodeAnalyzer->hasMixedArrayType($bracketsAwareUnionTypeNode)) {
+        if ($this->mixedArrayTypeNodeAnalyzer->hasMixedArrayType($unionTypeNode)) {
             return false;
         }
 
-        return ! $this->genericTypeNodeAnalyzer->hasGenericType($bracketsAwareUnionTypeNode);
+        return ! $this->genericTypeNodeAnalyzer->hasGenericType($unionTypeNode);
     }
 }

rules/DeadCode/PhpDoc/DeadReturnTagValueNodeAnalyzer.php

@@ -13,10 +13,10 @@
 use PHPStan\PhpDocParser\Ast\Type\GenericTypeNode;
 use PHPStan\PhpDocParser\Ast\Type\IdentifierTypeNode;
 use PHPStan\PhpDocParser\Ast\Type\ThisTypeNode;
+use PHPStan\PhpDocParser\Ast\Type\UnionTypeNode;
 use PHPStan\Type\TypeCombinator;
 use PHPStan\Type\UnionType;
 use Rector\BetterPhpDocParser\PhpDocManipulator\PhpDocTypeChanger;
-use Rector\BetterPhpDocParser\ValueObject\Type\BracketsAwareUnionTypeNode;
 use Rector\DeadCode\PhpDoc\Guard\StandaloneTypeRemovalGuard;
 use Rector\DeadCode\PhpDoc\Guard\TemplateTypeRemovalGuard;
 use Rector\DeadCode\TypeNodeAnalyzer\GenericTypeNodeAnalyzer;
@@ -79,7 +79,7 @@ public function isDead(ReturnTagValueNode $returnTagValueNode, ClassMethod|Funct
             return false;
         }
 
-        if (! $returnTagValueNode->type instanceof BracketsAwareUnionTypeNode) {
+        if (! $returnTagValueNode->type instanceof UnionTypeNode) {
             return $this->standaloneTypeRemovalGuard->isLegal($returnTagValueNode->type, $returnType);
         }
 
@@ -129,9 +129,9 @@ private function isDeadNotEqual(
         );
     }
 
-    private function hasTrueFalsePseudoType(BracketsAwareUnionTypeNode $bracketsAwareUnionTypeNode): bool
+    private function hasTrueFalsePseudoType(UnionTypeNode $unionTypeNode): bool
     {
-        $unionTypes = $bracketsAwareUnionTypeNode->types;
+        $unionTypes = $unionTypeNode->types;
 
         foreach ($unionTypes as $unionType) {
             if (! $unionType instanceof IdentifierTypeNode) {

rules/DeadCode/TypeNodeAnalyzer/GenericTypeNodeAnalyzer.php

@@ -6,13 +6,13 @@
 
 use PHPStan\PhpDocParser\Ast\Type\GenericTypeNode;
 use PHPStan\PhpDocParser\Ast\Type\TypeNode;
-use Rector\BetterPhpDocParser\ValueObject\Type\BracketsAwareUnionTypeNode;
+use PHPStan\PhpDocParser\Ast\Type\UnionTypeNode;
 
 final class GenericTypeNodeAnalyzer
 {
-    public function hasGenericType(BracketsAwareUnionTypeNode $bracketsAwareUnionTypeNode): bool
+    public function hasGenericType(UnionTypeNode $unionTypeNode): bool
     {
-        $types = $bracketsAwareUnionTypeNode->types;
+        $types = $unionTypeNode->types;
         return array_any($types, fn (TypeNode $typeNode): bool => $typeNode instanceof GenericTypeNode);
     }
 }

rules/DeadCode/TypeNodeAnalyzer/MixedArrayTypeNodeAnalyzer.php

@@ -4,18 +4,18 @@
 
 namespace Rector\DeadCode\TypeNodeAnalyzer;
 
+use PHPStan\PhpDocParser\Ast\Type\ArrayTypeNode;
 use PHPStan\PhpDocParser\Ast\Type\IdentifierTypeNode;
-use Rector\BetterPhpDocParser\ValueObject\Type\BracketsAwareUnionTypeNode;
-use Rector\BetterPhpDocParser\ValueObject\Type\SpacingAwareArrayTypeNode;
+use PHPStan\PhpDocParser\Ast\Type\UnionTypeNode;
 
 final class MixedArrayTypeNodeAnalyzer
 {
-    public function hasMixedArrayType(BracketsAwareUnionTypeNode $bracketsAwareUnionTypeNode): bool
+    public function hasMixedArrayType(UnionTypeNode $unionTypeNode): bool
     {
-        $types = $bracketsAwareUnionTypeNode->types;
+        $types = $unionTypeNode->types;
 
         foreach ($types as $type) {
-            if ($type instanceof SpacingAwareArrayTypeNode) {
+            if ($type instanceof ArrayTypeNode) {
                 $typeNode = $type->type;
                 if (! $typeNode instanceof IdentifierTypeNode) {
                     continue;

rules/Php80/Rector/Class_/AttributeValueResolver.php

@@ -62,7 +62,7 @@ public function resolve(
                         if ($docComment === '') {
                             $docComment .= $docValueLine;
                         } else {
-                            $docComment .= "\n * " . $docValueLine;
+                            $docComment .= "\n" . $docValueLine;
                         }
                     }
 

rules/TypeDeclarationDocblocks/Rector/ClassMethod/DocblockReturnArrayFromDirectArrayInstanceRector.php

@@ -10,12 +10,12 @@
 use PhpParser\Node\Stmt\Function_;
 use PhpParser\Node\Stmt\Return_;
 use PHPStan\PhpDocParser\Ast\PhpDoc\ReturnTagValueNode;
+use PHPStan\PhpDocParser\Ast\Type\ArrayTypeNode;
 use PHPStan\PhpDocParser\Ast\Type\IdentifierTypeNode;
 use PHPStan\Type\Constant\ConstantArrayType;
 use Rector\BetterPhpDocParser\PhpDocInfo\PhpDocInfo;
 use Rector\BetterPhpDocParser\PhpDocInfo\PhpDocInfoFactory;
 use Rector\BetterPhpDocParser\PhpDocManipulator\PhpDocTypeChanger;
-use Rector\BetterPhpDocParser\ValueObject\Type\SpacingAwareArrayTypeNode;
 use Rector\Rector\AbstractRector;
 use Rector\RuleDoc\CodeSample\CodeSample;
 use Rector\RuleDoc\RuleDefinition;
@@ -120,7 +120,7 @@ public function refactor(Node $node): ?Node
             $this->phpDocTypeChanger->changeReturnTypeNode(
                 $node,
                 $phpDocInfo,
-                new SpacingAwareArrayTypeNode(new IdentifierTypeNode('mixed'))
+                new ArrayTypeNode(new IdentifierTypeNode('mixed'))
             );
 
             return $node;

rules/TypeDeclarationDocblocks/Rector/Property/MergePhpstanDocTagIntoNativeRector.php

@@ -161,7 +161,7 @@ public function refactor(Node $node): ?Node
                     $tagValueNode->description = $nativeDescriptions[$this->resolveTagKey($tagValueNode)] ?? '';
                 }
 
-                $phpDocNode->children[$key] = new PhpDocTagNode($nativeTagName, $phpDocChildNode->value);
+                $phpDocChildNode->name = $nativeTagName;
                 $hasChanged = true;
             }
         }

rules/TypeDeclarationDocblocks/TagNodeAnalyzer/UsefulArrayTagNodeAnalyzer.php

@@ -7,9 +7,9 @@
 use PHPStan\PhpDocParser\Ast\PhpDoc\ParamTagValueNode;
 use PHPStan\PhpDocParser\Ast\PhpDoc\ReturnTagValueNode;
 use PHPStan\PhpDocParser\Ast\PhpDoc\VarTagValueNode;
+use PHPStan\PhpDocParser\Ast\Type\ArrayTypeNode;
 use PHPStan\PhpDocParser\Ast\Type\IdentifierTypeNode;
 use PHPStan\PhpDocParser\Ast\Type\TypeNode;
-use Rector\BetterPhpDocParser\ValueObject\Type\SpacingAwareArrayTypeNode;
 
 final class UsefulArrayTagNodeAnalyzer
 {
@@ -29,6 +29,6 @@ public function isUsefulArrayTag(null|ReturnTagValueNode|ParamTagValueNode|VarTa
 
     private function isMixedArray(TypeNode $typeNode): bool
     {
-        return $typeNode instanceof SpacingAwareArrayTypeNode && $typeNode->type instanceof IdentifierTypeNode && $typeNode->type->name === 'mixed';
+        return $typeNode instanceof ArrayTypeNode && $typeNode->type instanceof IdentifierTypeNode && $typeNode->type->name === 'mixed';
     }
 }