From bca4974b0b35e7a06cca93bc3c2399768c83ea91 Mon Sep 17 00:00:00 2001 From: Jaapio Date: Thu, 26 Aug 2021 15:40:21 +0200 Subject: [PATCH 1/3] Make split platform independend --- src/DocBlock/DescriptionFactory.php | 2 +- .../integration/InterpretingDocBlocksTest.php | 14 ++++++++++++-- .../unit/DocBlock/DescriptionFactoryTest.php | 4 +++- tests/unit/DocBlock/SerializerTest.php | 19 +++++++++++++------ tests/unit/DocBlockFactoryTest.php | 16 +++------------- 5 files changed, 32 insertions(+), 23 deletions(-) diff --git a/src/DocBlock/DescriptionFactory.php b/src/DocBlock/DescriptionFactory.php index b53b9c4..c125af0 100644 --- a/src/DocBlock/DescriptionFactory.php +++ b/src/DocBlock/DescriptionFactory.php @@ -146,7 +146,7 @@ class DescriptionFactory */ private function removeSuperfluousStartingWhitespace(string $contents): string { - $lines = explode("\n", $contents); + $lines = Utils::pregSplit("/\r\n?|\n/", $contents); // if there is only one line then we don't have lines with superfluous whitespace and // can use the contents as-is diff --git a/tests/integration/InterpretingDocBlocksTest.php b/tests/integration/InterpretingDocBlocksTest.php index 7ef37ba..2c8358c 100644 --- a/tests/integration/InterpretingDocBlocksTest.php +++ b/tests/integration/InterpretingDocBlocksTest.php @@ -79,7 +79,14 @@ DESCRIPTION; $this->assertInstanceOf(DocBlock::class, $docblock); $this->assertSame('This is an example of a summary.', $summary); $this->assertInstanceOf(Description::class, $description); - $this->assertSame($descriptionText, $description->render()); + $this->assertSame( + str_replace( + PHP_EOL, + "\n", + $descriptionText + ), + $description->render() + ); $this->assertEmpty($docblock->getTags()); } @@ -124,6 +131,9 @@ DESCRIPTION; include(__DIR__ . '/../../examples/playing-with-descriptions/02-escaping.php'); $this->assertSame( + str_replace( + PHP_EOL, + "\n", <<<'DESCRIPTION' You can escape the @-sign by surrounding it with braces, for example: @. And escape a closing brace within an inline tag by adding an opening brace in front of it like this: }. @@ -135,7 +145,7 @@ Here are example texts where you can see how they could be used in a real life s Do note that an {@internal inline tag that has an opening brace ({) does not break out}. DESCRIPTION - , + ), $foundDescription ); } diff --git a/tests/unit/DocBlock/DescriptionFactoryTest.php b/tests/unit/DocBlock/DescriptionFactoryTest.php index 237c650..394f845 100644 --- a/tests/unit/DocBlock/DescriptionFactoryTest.php +++ b/tests/unit/DocBlock/DescriptionFactoryTest.php @@ -20,6 +20,8 @@ use phpDocumentor\Reflection\DocBlock\Tags\Link as LinkTag; use phpDocumentor\Reflection\Types\Context; use PHPUnit\Framework\TestCase; +use function str_replace; + /** * @coversDefaultClass \phpDocumentor\Reflection\DocBlock\DescriptionFactory * @covers :: @@ -192,7 +194,7 @@ DESCRIPTION; $description = $factory->create($descriptionText, new Context('')); - $this->assertSame($expectedDescription, $description->render()); + $this->assertSame(str_replace(PHP_EOL, "\n", $expectedDescription), $description->render()); } /** diff --git a/tests/unit/DocBlock/SerializerTest.php b/tests/unit/DocBlock/SerializerTest.php index 28ca510..bf92744 100644 --- a/tests/unit/DocBlock/SerializerTest.php +++ b/tests/unit/DocBlock/SerializerTest.php @@ -63,7 +63,7 @@ DOCCOMMENT; ] ); - $this->assertSame($expected, $fixture->getDocComment($docBlock)); + $this->assertSameString($expected, $fixture->getDocComment($docBlock)); } /** @@ -98,7 +98,7 @@ DOCCOMMENT; ] ); - $this->assertSame($expected, $fixture->getDocComment($docBlock)); + $this->assertSameString($expected, $fixture->getDocComment($docBlock)); } /** @@ -133,7 +133,7 @@ DOCCOMMENT; ] ); - $this->assertSame($expected, $fixture->getDocComment($docBlock)); + $this->assertSameString($expected, $fixture->getDocComment($docBlock)); } /** @@ -174,7 +174,7 @@ DOCCOMMENT; ] ); - $this->assertSame($expected, $fixture->getDocComment($docBlock)); + $this->assertSameString($expected, $fixture->getDocComment($docBlock)); } /** @@ -198,9 +198,16 @@ DOCCOMMENT_AFTER_REMOVE; $genericTag = new DocBlock\Tags\Generic('unknown-tag'); $docBlock = new DocBlock('', null, [$genericTag]); - $this->assertSame($expected, $fixture->getDocComment($docBlock)); + $this->assertSameString($expected, $fixture->getDocComment($docBlock)); $docBlock->removeTag($genericTag); - $this->assertSame($expectedAfterRemove, $fixture->getDocComment($docBlock)); + $this->assertSameString($expectedAfterRemove, $fixture->getDocComment($docBlock)); + } + + public function assertSameString(string $expected, string $actual): void + { + $expected = str_replace(PHP_EOL, "\n", $expected); + + self::assertSame($expected, $actual); } } diff --git a/tests/unit/DocBlockFactoryTest.php b/tests/unit/DocBlockFactoryTest.php index 5fa429c..0397181 100644 --- a/tests/unit/DocBlockFactoryTest.php +++ b/tests/unit/DocBlockFactoryTest.php @@ -134,7 +134,7 @@ class DocBlockFactoryTest extends TestCase $docblock = $fixture->create($given); $this->assertSame($summary, $docblock->getSummary()); - $this->assertEquals(new Description($description), $docblock->getDescription()); + $this->assertEquals(new Description(str_replace(PHP_EOL, "\n", $description)), $docblock->getDescription()); } /** @@ -159,12 +159,7 @@ class DocBlockFactoryTest extends TestCase */ DOCBLOCK; - $description = <<create($given); @@ -180,14 +175,9 @@ DESCRIPTION; */ public function testTagsAreInterpretedUsingFactory(): void { - $tagString = << This is with - multiline description. -TAG; - $tag = m::mock(Tag::class); $tagFactory = m::mock(TagFactory::class); - $tagFactory->shouldReceive('create')->with($tagString, m::type(Context::class))->andReturn($tag); + $tagFactory->shouldReceive('create')->with(m::any(), m::type(Context::class))->andReturn($tag); $fixture = new DocBlockFactory(new DescriptionFactory($tagFactory), $tagFactory); From c5e702d29974213c97ad642be59b2028ed411973 Mon Sep 17 00:00:00 2001 From: Jaapio Date: Thu, 26 Aug 2021 17:11:14 +0200 Subject: [PATCH 2/3] Allow serializer to have a configurable line-ending --- examples/03-reconstituting-a-docblock.php | 2 +- examples/04-adding-your-own-tag.php | 2 +- src/DocBlock/Serializer.php | 11 +++++++++-- 3 files changed, 11 insertions(+), 4 deletions(-) diff --git a/examples/03-reconstituting-a-docblock.php b/examples/03-reconstituting-a-docblock.php index 6bc10ba..482a6dd 100644 --- a/examples/03-reconstituting-a-docblock.php +++ b/examples/03-reconstituting-a-docblock.php @@ -20,7 +20,7 @@ $factory = DocBlockFactory::createInstance(); $docblock = $factory->create($docComment); // Create the serializer that will reconstitute the DocBlock back to its original form. -$serializer = new Serializer(); +$serializer = new Serializer(0, '', true, null, null, PHP_EOL); // Reconstitution is performed by the `getDocComment()` method. $reconstitutedDocComment = $serializer->getDocComment($docblock); diff --git a/examples/04-adding-your-own-tag.php b/examples/04-adding-your-own-tag.php index 63ba5bf..33affb1 100644 --- a/examples/04-adding-your-own-tag.php +++ b/examples/04-adding-your-own-tag.php @@ -126,5 +126,5 @@ $customTagObjects = $docblock->getTagsByName('my-tag'); // As an experiment: let's reconstitute the DocBlock and observe that because we added a __toString() method // to the tag class that we can now also see it. -$serializer = new Serializer(); +$serializer = new Serializer(0, '',true, null, null, PHP_EOL); $reconstitutedDocComment = $serializer->getDocComment($docblock); diff --git a/src/DocBlock/Serializer.php b/src/DocBlock/Serializer.php index 37f4fb8..59e1671 100644 --- a/src/DocBlock/Serializer.php +++ b/src/DocBlock/Serializer.php @@ -42,6 +42,10 @@ class Serializer /** @var Formatter A custom tag formatter. */ protected $tagFormatter; + /** + * @var string + */ + private $lineEnding; /** * Create a Serializer instance. @@ -51,19 +55,22 @@ class Serializer * @param bool $indentFirstLine Whether to indent the first line. * @param int|null $lineLength The max length of a line or NULL to disable line wrapping. * @param Formatter $tagFormatter A custom tag formatter, defaults to PassthroughFormatter. + * @param string $lineEnding Line ending used in the output, by default \n is used. */ public function __construct( int $indent = 0, string $indentString = ' ', bool $indentFirstLine = true, ?int $lineLength = null, - ?Formatter $tagFormatter = null + ?Formatter $tagFormatter = null, + string $lineEnding = "\n" ) { $this->indent = $indent; $this->indentString = $indentString; $this->isFirstLineIndented = $indentFirstLine; $this->lineLength = $lineLength; $this->tagFormatter = $tagFormatter ?: new PassthroughFormatter(); + $this->lineEnding = $lineEnding; } /** @@ -96,7 +103,7 @@ class Serializer $comment = $this->addTagBlock($docblock, $wrapLength, $indent, $comment); - return $comment . $indent . ' */'; + return str_replace("\n", $this->lineEnding, $comment . $indent . ' */'); } private function removeTrailingSpaces(string $indent, string $text): string From 6fa60f9f081d3d3de86619ae37ec16425b413609 Mon Sep 17 00:00:00 2001 From: Jaapio Date: Thu, 26 Aug 2021 22:24:22 +0200 Subject: [PATCH 3/3] Fix code style --- src/DocBlock/DescriptionFactory.php | 1 - src/DocBlock/Serializer.php | 4 +--- src/DocBlock/Tag.php | 1 - src/DocBlock/Tags/Method.php | 5 +---- src/Utils.php | 2 +- tests/unit/DocBlock/DescriptionFactoryTest.php | 2 ++ tests/unit/DocBlock/SerializerTest.php | 4 ++++ tests/unit/DocBlock/StandardTagFactoryTest.php | 2 -- tests/unit/DocBlockFactoryTest.php | 4 ++++ 9 files changed, 13 insertions(+), 12 deletions(-) diff --git a/src/DocBlock/DescriptionFactory.php b/src/DocBlock/DescriptionFactory.php index c125af0..1a519ec 100644 --- a/src/DocBlock/DescriptionFactory.php +++ b/src/DocBlock/DescriptionFactory.php @@ -17,7 +17,6 @@ use phpDocumentor\Reflection\Types\Context as TypeContext; use phpDocumentor\Reflection\Utils; use function count; -use function explode; use function implode; use function ltrim; use function min; diff --git a/src/DocBlock/Serializer.php b/src/DocBlock/Serializer.php index 59e1671..77e5fb5 100644 --- a/src/DocBlock/Serializer.php +++ b/src/DocBlock/Serializer.php @@ -42,9 +42,7 @@ class Serializer /** @var Formatter A custom tag formatter. */ protected $tagFormatter; - /** - * @var string - */ + /** @var string */ private $lineEnding; /** diff --git a/src/DocBlock/Tag.php b/src/DocBlock/Tag.php index 2f15436..7cf07b4 100644 --- a/src/DocBlock/Tag.php +++ b/src/DocBlock/Tag.php @@ -21,7 +21,6 @@ interface Tag /** * @return Tag|mixed Class that implements Tag - * * @phpstan-return ?Tag */ public static function create(string $body); diff --git a/src/DocBlock/Tags/Method.php b/src/DocBlock/Tags/Method.php index 32e99f7..f08bfff 100644 --- a/src/DocBlock/Tags/Method.php +++ b/src/DocBlock/Tags/Method.php @@ -59,7 +59,6 @@ final class Method extends BaseTag implements Factory\StaticMethod /** * @param array> $arguments - * * @phpstan-param array $arguments */ public function __construct( @@ -186,7 +185,6 @@ final class Method extends BaseTag implements Factory\StaticMethod /** * @return array> - * * @phpstan-return array */ public function getArguments(): array @@ -239,10 +237,9 @@ final class Method extends BaseTag implements Factory\StaticMethod /** * @param mixed[][]|string[] $arguments + * @phpstan-param array $arguments * * @return mixed[][] - * - * @phpstan-param array $arguments * @phpstan-return array */ private function filterArguments(array $arguments = []): array diff --git a/src/Utils.php b/src/Utils.php index 2c544a0..ddd0f61 100644 --- a/src/Utils.php +++ b/src/Utils.php @@ -14,8 +14,8 @@ declare(strict_types=1); namespace phpDocumentor\Reflection; use phpDocumentor\Reflection\Exception\PcreException; - use Webmozart\Assert\Assert; + use function preg_last_error; use function preg_split as php_preg_split; diff --git a/tests/unit/DocBlock/DescriptionFactoryTest.php b/tests/unit/DocBlock/DescriptionFactoryTest.php index 394f845..7fc90ef 100644 --- a/tests/unit/DocBlock/DescriptionFactoryTest.php +++ b/tests/unit/DocBlock/DescriptionFactoryTest.php @@ -22,6 +22,8 @@ use PHPUnit\Framework\TestCase; use function str_replace; +use const PHP_EOL; + /** * @coversDefaultClass \phpDocumentor\Reflection\DocBlock\DescriptionFactory * @covers :: diff --git a/tests/unit/DocBlock/SerializerTest.php b/tests/unit/DocBlock/SerializerTest.php index bf92744..57f1abc 100644 --- a/tests/unit/DocBlock/SerializerTest.php +++ b/tests/unit/DocBlock/SerializerTest.php @@ -17,6 +17,10 @@ use Mockery as m; use phpDocumentor\Reflection\DocBlock; use PHPUnit\Framework\TestCase; +use function str_replace; + +use const PHP_EOL; + /** * @coversDefaultClass \phpDocumentor\Reflection\DocBlock\Serializer * @covers :: diff --git a/tests/unit/DocBlock/StandardTagFactoryTest.php b/tests/unit/DocBlock/StandardTagFactoryTest.php index 037d563..2e380d9 100644 --- a/tests/unit/DocBlock/StandardTagFactoryTest.php +++ b/tests/unit/DocBlock/StandardTagFactoryTest.php @@ -462,7 +462,6 @@ class StandardTagFactoryTest extends TestCase /** * @return string[][] - * * @phpstan-return array> */ public function validTagProvider(): array @@ -526,7 +525,6 @@ class StandardTagFactoryTest extends TestCase /** * @return string[][] - * * @phpstan-return list> */ public function invalidTagProvider(): array diff --git a/tests/unit/DocBlockFactoryTest.php b/tests/unit/DocBlockFactoryTest.php index 0397181..762a7ac 100644 --- a/tests/unit/DocBlockFactoryTest.php +++ b/tests/unit/DocBlockFactoryTest.php @@ -23,6 +23,10 @@ use phpDocumentor\Reflection\Types\Context; use PHPUnit\Framework\TestCase; use ReflectionClass; +use function str_replace; + +use const PHP_EOL; + /** * @uses \Webmozart\Assert\Assert * @uses \phpDocumentor\Reflection\DocBlock