diff --git a/.gitattributes b/.gitattributes index 64f9e3c6..f269eda9 100644 --- a/.gitattributes +++ b/.gitattributes @@ -9,7 +9,9 @@ /phive.xml export-ignore /phpcs.xml.dist export-ignore /phpstan.neon export-ignore +/phpstan-baseline.neon export-ignore /psalm.xml export-ignore +/phpdoc.dist.xml export-ignore /tests/ export-ignore -/examples/ export-ignore +/docs/ export-ignore /.github/ export-ignore diff --git a/README.md b/README.md index df426a0a..9754ba68 100644 --- a/README.md +++ b/README.md @@ -71,4 +71,4 @@ $description = (string) $docblock->getDescription(); $description = $docblock->getDescription()->render(); ``` -> For more examples it would be best to review the scripts in the [`/examples` folder](/examples). +> For more examples it would be best to review the scripts in the [`/docs/examples` folder](/docs/examples). diff --git a/composer.lock b/composer.lock index 77d66b46..27169fcc 100644 --- a/composer.lock +++ b/composer.lock @@ -8,29 +8,29 @@ "packages": [ { "name": "doctrine/deprecations", - "version": "1.1.5", + "version": "1.1.6", "source": { "type": "git", "url": "https://github.com/doctrine/deprecations.git", - "reference": "459c2f5dd3d6a4633d3b5f46ee2b1c40f57d3f38" + "reference": "d4fe3e6fd9bb9e72557a19674f44d8ac7db4c6ca" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/doctrine/deprecations/zipball/459c2f5dd3d6a4633d3b5f46ee2b1c40f57d3f38", - "reference": "459c2f5dd3d6a4633d3b5f46ee2b1c40f57d3f38", + "url": "https://api.github.com/repos/doctrine/deprecations/zipball/d4fe3e6fd9bb9e72557a19674f44d8ac7db4c6ca", + "reference": "d4fe3e6fd9bb9e72557a19674f44d8ac7db4c6ca", "shasum": "" }, "require": { "php": "^7.1 || ^8.0" }, "conflict": { - "phpunit/phpunit": "<=7.5 || >=13" + "phpunit/phpunit": "<=7.5 || >=14" }, "require-dev": { - "doctrine/coding-standard": "^9 || ^12 || ^13", - "phpstan/phpstan": "1.4.10 || 2.1.11", + "doctrine/coding-standard": "^9 || ^12 || ^14", + "phpstan/phpstan": "1.4.10 || 2.1.30", "phpstan/phpstan-phpunit": "^1.0 || ^2", - "phpunit/phpunit": "^7.5 || ^8.5 || ^9.6 || ^10.5 || ^11.5 || ^12", + "phpunit/phpunit": "^7.5 || ^8.5 || ^9.6 || ^10.5 || ^11.5 || ^12.4 || ^13.0", "psr/log": "^1 || ^2 || ^3" }, "suggest": { @@ -50,9 +50,9 @@ "homepage": "https://www.doctrine-project.org/", "support": { "issues": "https://github.com/doctrine/deprecations/issues", - "source": "https://github.com/doctrine/deprecations/tree/1.1.5" + "source": "https://github.com/doctrine/deprecations/tree/1.1.6" }, - "time": "2025-04-07T20:06:18+00:00" + "time": "2026-02-07T07:09:04+00:00" }, { "name": "phpdocumentor/reflection-common", @@ -538,16 +538,16 @@ }, { "name": "nikic/php-parser", - "version": "v5.6.2", + "version": "v5.7.0", "source": { "type": "git", "url": "https://github.com/nikic/PHP-Parser.git", - "reference": "3a454ca033b9e06b63282ce19562e892747449bb" + "reference": "dca41cd15c2ac9d055ad70dbfd011130757d1f82" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/nikic/PHP-Parser/zipball/3a454ca033b9e06b63282ce19562e892747449bb", - "reference": "3a454ca033b9e06b63282ce19562e892747449bb", + "url": "https://api.github.com/repos/nikic/PHP-Parser/zipball/dca41cd15c2ac9d055ad70dbfd011130757d1f82", + "reference": "dca41cd15c2ac9d055ad70dbfd011130757d1f82", "shasum": "" }, "require": { @@ -590,9 +590,9 @@ ], "support": { "issues": "https://github.com/nikic/PHP-Parser/issues", - "source": "https://github.com/nikic/PHP-Parser/tree/v5.6.2" + "source": "https://github.com/nikic/PHP-Parser/tree/v5.7.0" }, - "time": "2025-10-21T19:32:17+00:00" + "time": "2025-12-06T11:56:16+00:00" }, { "name": "phar-io/manifest", @@ -1235,16 +1235,16 @@ }, { "name": "phpunit/phpunit", - "version": "9.6.29", + "version": "9.6.33", "source": { "type": "git", "url": "https://github.com/sebastianbergmann/phpunit.git", - "reference": "9ecfec57835a5581bc888ea7e13b51eb55ab9dd3" + "reference": "fea06253ecc0a32faf787bd31b261f56f351d049" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/sebastianbergmann/phpunit/zipball/9ecfec57835a5581bc888ea7e13b51eb55ab9dd3", - "reference": "9ecfec57835a5581bc888ea7e13b51eb55ab9dd3", + "url": "https://api.github.com/repos/sebastianbergmann/phpunit/zipball/fea06253ecc0a32faf787bd31b261f56f351d049", + "reference": "fea06253ecc0a32faf787bd31b261f56f351d049", "shasum": "" }, "require": { @@ -1266,7 +1266,7 @@ "phpunit/php-timer": "^5.0.3", "sebastian/cli-parser": "^1.0.2", "sebastian/code-unit": "^1.0.8", - "sebastian/comparator": "^4.0.9", + "sebastian/comparator": "^4.0.10", "sebastian/diff": "^4.0.6", "sebastian/environment": "^5.1.5", "sebastian/exporter": "^4.0.8", @@ -1318,7 +1318,7 @@ "support": { "issues": "https://github.com/sebastianbergmann/phpunit/issues", "security": "https://github.com/sebastianbergmann/phpunit/security/policy", - "source": "https://github.com/sebastianbergmann/phpunit/tree/9.6.29" + "source": "https://github.com/sebastianbergmann/phpunit/tree/9.6.33" }, "funding": [ { @@ -1342,7 +1342,7 @@ "type": "tidelift" } ], - "time": "2025-09-24T06:29:11+00:00" + "time": "2026-01-27T05:25:09+00:00" }, { "name": "psalm/phar", @@ -1548,16 +1548,16 @@ }, { "name": "sebastian/comparator", - "version": "4.0.9", + "version": "4.0.10", "source": { "type": "git", "url": "https://github.com/sebastianbergmann/comparator.git", - "reference": "67a2df3a62639eab2cc5906065e9805d4fd5dfc5" + "reference": "e4df00b9b3571187db2831ae9aada2c6efbd715d" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/sebastianbergmann/comparator/zipball/67a2df3a62639eab2cc5906065e9805d4fd5dfc5", - "reference": "67a2df3a62639eab2cc5906065e9805d4fd5dfc5", + "url": "https://api.github.com/repos/sebastianbergmann/comparator/zipball/e4df00b9b3571187db2831ae9aada2c6efbd715d", + "reference": "e4df00b9b3571187db2831ae9aada2c6efbd715d", "shasum": "" }, "require": { @@ -1610,7 +1610,7 @@ ], "support": { "issues": "https://github.com/sebastianbergmann/comparator/issues", - "source": "https://github.com/sebastianbergmann/comparator/tree/4.0.9" + "source": "https://github.com/sebastianbergmann/comparator/tree/4.0.10" }, "funding": [ { @@ -1630,7 +1630,7 @@ "type": "tidelift" } ], - "time": "2025-08-10T06:51:50+00:00" + "time": "2026-01-24T09:22:56+00:00" }, { "name": "sebastian/complexity", @@ -2523,5 +2523,5 @@ "platform-overrides": { "php": "7.4.0" }, - "plugin-api-version": "2.9.0" + "plugin-api-version": "2.6.0" } diff --git a/src/DocBlock/Tags/Factory/AbstractPHPStanFactory.php b/src/DocBlock/Tags/Factory/AbstractPHPStanFactory.php index 35a981e5..770a09a3 100644 --- a/src/DocBlock/Tags/Factory/AbstractPHPStanFactory.php +++ b/src/DocBlock/Tags/Factory/AbstractPHPStanFactory.php @@ -25,9 +25,10 @@ use PHPStan\PhpDocParser\ParserConfig; use RuntimeException; -use function ltrim; use function property_exists; use function rtrim; +use function str_replace; +use function trim; /** * Factory class creating tags using phpstan's parser @@ -61,7 +62,7 @@ public function __construct(PHPStanFactory ...$factories) public function create(string $tagLine, ?TypeContext $context = null): Tag { try { - $tokens = $this->tokenizeLine($tagLine . "\n"); + $tokens = $this->tokenizeLine($tagLine); $ast = $this->parser->parseTag($tokens); if (property_exists($ast->value, 'description') === true) { $ast->value->setAttribute( @@ -104,20 +105,20 @@ public function create(string $tagLine, ?TypeContext $context = null): Tag */ private function tokenizeLine(string $tagLine): TokenIterator { - $tokens = $this->lexer->tokenize($tagLine); + // Prefix continuation lines with "* ", which is consumed by the phpstan parser as TOKEN_PHPDOC_EOL. + $tagLine = str_replace("\n", "\n* ", $tagLine); + $tokens = $this->lexer->tokenize($tagLine . "\n"); $fixed = []; foreach ($tokens as $token) { - if (($token[1] === Lexer::TOKEN_PHPDOC_EOL) && rtrim($token[0], " \t") !== $token[0]) { + if ($token[Lexer::TYPE_OFFSET] === Lexer::TOKEN_PHPDOC_EOL) { + // Strip "* " prefix (and other horizontal whitespace) again so it doesn't and up in the + // description when we joinUntil() in create(). $fixed[] = [ - rtrim($token[Lexer::VALUE_OFFSET], " \t"), - Lexer::TOKEN_PHPDOC_EOL, - $token[2] ?? 0, - ]; - $fixed[] = [ - ltrim($token[Lexer::VALUE_OFFSET], "\n\r"), - Lexer::TOKEN_HORIZONTAL_WS, - ($token[2] ?? 0) + 1, + Lexer::VALUE_OFFSET => trim($token[Lexer::VALUE_OFFSET], "* \t"), + Lexer::TYPE_OFFSET => $token[Lexer::TYPE_OFFSET], + Lexer::LINE_OFFSET => $token[Lexer::LINE_OFFSET] ?? 0, ]; + continue; } diff --git a/tests/integration/InterpretingDocBlocksTest.php b/tests/integration/InterpretingDocBlocksTest.php index 4ea86680..4d5e9dba 100644 --- a/tests/integration/InterpretingDocBlocksTest.php +++ b/tests/integration/InterpretingDocBlocksTest.php @@ -489,4 +489,43 @@ public function testParamTagDescriptionIsCorrectly(): void self::assertSame('Lorem ipsum dolor sit amet, consectetur adipiscing elit. Maecenas varius, tellus in cursus dictum, justo odio sagittis velit, id iaculis mi dui id nisi.', (string) $paramTags->getDescription()); } + + public function testParamBlockDescriptionPreservesStarContinuationLines(): void + { + $docComment = <<create($docComment); + + self::assertEquals( + [ + new Param( + 'foo', + new Array_(), + false, + new Description(<<<'DESCRIPTION' +{ + Description of foo. + + @type string $bar Description of bar with + * a list + * spanning *multiple* lines +} +DESCRIPTION + ), + ), + ], + $docblock->getTags() + ); + } }