Skip to content

Commit c054cfd

Browse files
jaapiojaapio
committed
Fixes implementation of Example tag
1 parent a8d791f commit c054cfd

File tree

2 files changed

+167
-48
lines changed

2 files changed

+167
-48
lines changed

‎src/DocBlock/Tags/Example.php

Lines changed: 65 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,9 @@
1212

1313
namespace phpDocumentor\Reflection\DocBlock\Tags;
1414

15+
use phpDocumentor\Reflection\DocBlock\Description;
1516
use phpDocumentor\Reflection\DocBlock\Tag;
17+
use Webmozart\Assert\Assert;
1618

1719
/**
1820
* Reflection class for a {@}example tag in a Docblock.
@@ -22,14 +24,40 @@ final class Example extends BaseTag
2224
/**
2325
* @var string Path to a file to use as an example. May also be an absolute URI.
2426
*/
25-
private $filePath = '';
27+
private $filePath;
2628

2729
/**
2830
* @var bool Whether the file path component represents an URI. This determines how the file portion
2931
* appears at {@link getContent()}.
3032
*/
3133
private $isURI = false;
3234

35+
/**
36+
* @var
37+
*/
38+
private $startingLine;
39+
40+
/**
41+
* @var
42+
*/
43+
private $lineCount;
44+
45+
public function __construct($filePath, $isURI, $startingLine, $lineCount, $description)
46+
{
47+
Assert::notEmpty($filePath);
48+
Assert::integer($startingLine);
49+
Assert::greaterThanEq($startingLine, 0);
50+
51+
$this->filePath = $filePath;
52+
$this->startingLine = $startingLine;
53+
$this->lineCount = $lineCount;
54+
if ($description !== null) {
55+
$this->description = trim($description);
56+
}
57+
58+
$this->isURI = $isURI;
59+
}
60+
3361
/**
3462
* {@inheritdoc}
3563
*/
@@ -43,7 +71,7 @@ public function getContent()
4371
:$this->filePath;
4472
}
4573

46-
$this->description = $filePath . ' ' . parent::getContent();
74+
return trim($filePath . ' ' . parent::getDescription());
4775
}
4876

4977
return $this->description;
@@ -71,16 +99,29 @@ public static function create($body)
7199
$lineCount = null;
72100
$description = null;
73101

74-
// Starting line / Number of lines / Description
75-
if (preg_match('/^([1-9]\d*)\s*(?:((?1))\s+)?(.*)$/sux', $matches[3], $matches)) {
76-
$startingLine = (int)$matches[1];
77-
if (isset($matches[2]) && $matches[2] !== '') {
78-
$lineCount = (int)$matches[2];
79-
}
102+
if (array_key_exists(3, $matches)) {
80103
$description = $matches[3];
104+
105+
// Starting line / Number of lines / Description
106+
if (preg_match('/^([1-9]\d*)(?:\s+((?1))\s*)?(.*)$/sux', $matches[3], $contentMatches)) {
107+
$startingLine = (int)$contentMatches[1];
108+
if (isset($contentMatches[2]) && $contentMatches[2] !== '') {
109+
$lineCount = (int)$contentMatches[2];
110+
}
111+
112+
if (array_key_exists(3, $contentMatches)) {
113+
$description = $contentMatches[3];
114+
}
115+
}
81116
}
82117

83-
return new static($filePath, $fileUri, $startingLine, $lineCount, $description);
118+
return new static(
119+
$filePath !== null?$filePath:$fileUri,
120+
$fileUri !== null,
121+
$startingLine,
122+
$lineCount,
123+
$description
124+
);
84125
}
85126

86127
/**
@@ -95,64 +136,40 @@ public function getFilePath()
95136
}
96137

97138
/**
98-
* Sets the file path.
99-
*
100-
* @param string $filePath The new file path to use for the example.
139+
* Returns a string representation for this tag.
101140
*
102-
* @return $this
141+
* @return string
103142
*/
104-
public function setFilePath($filePath)
143+
public function __toString()
105144
{
106-
$this->isURI = false;
107-
$this->filePath = trim($filePath);
108-
109-
$this->description = null;
110-
return $this;
145+
return $this->filePath . ($this->description ? ' ' . $this->description : '');
111146
}
112147

113148
/**
114-
* Sets the file path as an URI.
115-
*
116-
* This function is equivalent to {@link setFilePath()}, except that it
117-
* converts an URI to a file path before that.
118-
*
119-
* There is no getFileURI(), as {@link getFilePath()} is compatible.
149+
* Returns true if the provided URI is relative or contains a complete scheme (and thus is absolute).
120150
*
121-
* @param string $uri The new file URI to use as an example.
151+
* @param string $uri
122152
*
123-
* @return $this
153+
* @return bool
124154
*/
125-
public function setFileURI($uri)
155+
private function isUriRelative($uri)
126156
{
127-
$this->isURI = true;
128-
$this->description = null;
129-
130-
$this->filePath = $this->isUriRelative($uri)
131-
? rawurldecode(str_replace(array('/', '\\'), '%2F', $uri))
132-
: $this->filePath = $uri;
133-
134-
return $this;
157+
return false === strpos($uri, ':');
135158
}
136159

137160
/**
138-
* Returns a string representation for this tag.
139-
*
140-
* @return string
161+
* @return int
141162
*/
142-
public function __toString()
163+
public function getStartingLine()
143164
{
144-
return $this->filePath . ($this->description ? ' ' . $this->description->render() : '');
165+
return $this->startingLine;
145166
}
146167

147168
/**
148-
* Returns true if the provided URI is relative or contains a complete scheme (and thus is absolute).
149-
*
150-
* @param string $uri
151-
*
152-
* @return bool
169+
* @return int
153170
*/
154-
private function isUriRelative($uri)
171+
public function getLineCount()
155172
{
156-
return false === strpos($uri, ':');
173+
return $this->lineCount;
157174
}
158175
}

‎tests/unit/DocBlock/Tags/ExampleTest.php

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
<?php
2+
3+
namespace DocBlock\Tags;
4+
5+
use phpDocumentor\Reflection\DocBlock\Tags\Example;
6+
7+
/**
8+
* @coversDefaultClass \phpDocumentor\Reflection\DocBlock\Tags\Example
9+
*/
10+
class ExampleTest extends \PHPUnit_Framework_TestCase
11+
{
12+
/**
13+
* @covers ::create
14+
* @covers ::__construct
15+
* @covers ::getContent
16+
* @uses phpDocumentor\Reflection\DocBlock\Tags\BaseTag
17+
*/
18+
public function testExampleWithoutContent()
19+
{
20+
$tag = Example::create('"example1.php"');
21+
$this->assertEquals('"example1.php"', $tag->getContent());
22+
$this->assertEquals('', $tag->getDescription());
23+
}
24+
25+
/**
26+
* @covers ::create
27+
* @covers ::__construct
28+
* @covers ::getFilePath
29+
* @covers ::getDescription
30+
* @uses phpDocumentor\Reflection\DocBlock\Tags\BaseTag
31+
*/
32+
public function testWithDescription()
33+
{
34+
$tag = Example::create('"example1.php" some text');
35+
$this->assertEquals('example1.php', $tag->getFilePath());
36+
$this->assertEquals('some text', $tag->getDescription());
37+
}
38+
39+
/**
40+
* @covers ::create
41+
* @covers ::__construct
42+
* @covers ::getFilePath
43+
* @covers ::getStartingLine
44+
* @uses phpDocumentor\Reflection\DocBlock\Tags\BaseTag
45+
*/
46+
public function testStartlineIsParsed()
47+
{
48+
$tag = Example::create('"example1.php" 10');
49+
$this->assertEquals('example1.php', $tag->getFilePath());
50+
$this->assertEquals(10, $tag->getStartingLine());
51+
}
52+
53+
/**
54+
* @covers ::create
55+
* @covers ::__construct
56+
* @covers ::getFilePath
57+
* @covers ::getStartingLine
58+
* @covers ::getDescription
59+
* @uses phpDocumentor\Reflection\DocBlock\Tags\BaseTag
60+
*/
61+
public function testAllowOmitingLineCount()
62+
{
63+
$tag = Example::create('"example1.php" 10 some text');
64+
$this->assertEquals('example1.php', $tag->getFilePath());
65+
$this->assertEquals(10, $tag->getStartingLine());
66+
$this->assertEquals('some text', $tag->getDescription());
67+
}
68+
69+
/**
70+
* @covers ::create
71+
* @covers ::__construct
72+
* @covers ::getFilePath
73+
* @covers ::getStartingLine
74+
* @covers ::getLineCount
75+
* @uses phpDocumentor\Reflection\DocBlock\Tags\BaseTag
76+
*/
77+
public function testLengthIsParsed()
78+
{
79+
$tag = Example::create('"example1.php" 10 5');
80+
$this->assertEquals('example1.php', $tag->getFilePath());
81+
$this->assertEquals(10, $tag->getStartingLine());
82+
$this->assertEquals(5, $tag->getLineCount());
83+
}
84+
85+
/**
86+
* @covers ::create
87+
* @covers ::__construct
88+
* @covers ::getFilePath
89+
* @covers ::getStartingLine
90+
* @covers ::getLineCount
91+
* @covers ::getDescription
92+
* @uses phpDocumentor\Reflection\DocBlock\Tags\BaseTag
93+
*/
94+
public function testFullExample()
95+
{
96+
$tag = Example::create('"example1.php" 10 5 test text');
97+
$this->assertEquals('example1.php', $tag->getFilePath());
98+
$this->assertEquals(10, $tag->getStartingLine());
99+
$this->assertEquals(5, $tag->getLineCount());
100+
$this->assertEquals('test text', $tag->getDescription());
101+
}
102+
}

0 commit comments

Comments
 (0)