Chris@12
|
1 <?php
|
Chris@12
|
2 /**
|
Chris@12
|
3 * This file is part of phpDocumentor.
|
Chris@12
|
4 *
|
Chris@12
|
5 * For the full copyright and license information, please view the LICENSE
|
Chris@12
|
6 * file that was distributed with this source code.
|
Chris@12
|
7 *
|
Chris@12
|
8 * @copyright 2010-2015 Mike van Riel<mike@phpdoc.org>
|
Chris@12
|
9 * @license http://www.opensource.org/licenses/mit-license.php MIT
|
Chris@12
|
10 * @link http://phpdoc.org
|
Chris@12
|
11 */
|
Chris@12
|
12
|
Chris@12
|
13 namespace phpDocumentor\Reflection;
|
Chris@12
|
14
|
Chris@12
|
15 use phpDocumentor\Reflection\DocBlock\Tag;
|
Chris@12
|
16 use Webmozart\Assert\Assert;
|
Chris@12
|
17
|
Chris@12
|
18 final class DocBlock
|
Chris@12
|
19 {
|
Chris@12
|
20 /** @var string The opening line for this docblock. */
|
Chris@12
|
21 private $summary = '';
|
Chris@12
|
22
|
Chris@12
|
23 /** @var DocBlock\Description The actual description for this docblock. */
|
Chris@12
|
24 private $description = null;
|
Chris@12
|
25
|
Chris@12
|
26 /** @var Tag[] An array containing all the tags in this docblock; except inline. */
|
Chris@12
|
27 private $tags = [];
|
Chris@12
|
28
|
Chris@12
|
29 /** @var Types\Context Information about the context of this DocBlock. */
|
Chris@12
|
30 private $context = null;
|
Chris@12
|
31
|
Chris@12
|
32 /** @var Location Information about the location of this DocBlock. */
|
Chris@12
|
33 private $location = null;
|
Chris@12
|
34
|
Chris@12
|
35 /** @var bool Is this DocBlock (the start of) a template? */
|
Chris@12
|
36 private $isTemplateStart = false;
|
Chris@12
|
37
|
Chris@12
|
38 /** @var bool Does this DocBlock signify the end of a DocBlock template? */
|
Chris@12
|
39 private $isTemplateEnd = false;
|
Chris@12
|
40
|
Chris@12
|
41 /**
|
Chris@12
|
42 * @param string $summary
|
Chris@12
|
43 * @param DocBlock\Description $description
|
Chris@12
|
44 * @param DocBlock\Tag[] $tags
|
Chris@12
|
45 * @param Types\Context $context The context in which the DocBlock occurs.
|
Chris@12
|
46 * @param Location $location The location within the file that this DocBlock occurs in.
|
Chris@12
|
47 * @param bool $isTemplateStart
|
Chris@12
|
48 * @param bool $isTemplateEnd
|
Chris@12
|
49 */
|
Chris@12
|
50 public function __construct(
|
Chris@12
|
51 $summary = '',
|
Chris@12
|
52 DocBlock\Description $description = null,
|
Chris@12
|
53 array $tags = [],
|
Chris@12
|
54 Types\Context $context = null,
|
Chris@12
|
55 Location $location = null,
|
Chris@12
|
56 $isTemplateStart = false,
|
Chris@12
|
57 $isTemplateEnd = false
|
Chris@12
|
58 ) {
|
Chris@12
|
59 Assert::string($summary);
|
Chris@12
|
60 Assert::boolean($isTemplateStart);
|
Chris@12
|
61 Assert::boolean($isTemplateEnd);
|
Chris@12
|
62 Assert::allIsInstanceOf($tags, Tag::class);
|
Chris@12
|
63
|
Chris@12
|
64 $this->summary = $summary;
|
Chris@12
|
65 $this->description = $description ?: new DocBlock\Description('');
|
Chris@12
|
66 foreach ($tags as $tag) {
|
Chris@12
|
67 $this->addTag($tag);
|
Chris@12
|
68 }
|
Chris@12
|
69
|
Chris@12
|
70 $this->context = $context;
|
Chris@12
|
71 $this->location = $location;
|
Chris@12
|
72
|
Chris@12
|
73 $this->isTemplateEnd = $isTemplateEnd;
|
Chris@12
|
74 $this->isTemplateStart = $isTemplateStart;
|
Chris@12
|
75 }
|
Chris@12
|
76
|
Chris@12
|
77 /**
|
Chris@12
|
78 * @return string
|
Chris@12
|
79 */
|
Chris@12
|
80 public function getSummary()
|
Chris@12
|
81 {
|
Chris@12
|
82 return $this->summary;
|
Chris@12
|
83 }
|
Chris@12
|
84
|
Chris@12
|
85 /**
|
Chris@12
|
86 * @return DocBlock\Description
|
Chris@12
|
87 */
|
Chris@12
|
88 public function getDescription()
|
Chris@12
|
89 {
|
Chris@12
|
90 return $this->description;
|
Chris@12
|
91 }
|
Chris@12
|
92
|
Chris@12
|
93 /**
|
Chris@12
|
94 * Returns the current context.
|
Chris@12
|
95 *
|
Chris@12
|
96 * @return Types\Context
|
Chris@12
|
97 */
|
Chris@12
|
98 public function getContext()
|
Chris@12
|
99 {
|
Chris@12
|
100 return $this->context;
|
Chris@12
|
101 }
|
Chris@12
|
102
|
Chris@12
|
103 /**
|
Chris@12
|
104 * Returns the current location.
|
Chris@12
|
105 *
|
Chris@12
|
106 * @return Location
|
Chris@12
|
107 */
|
Chris@12
|
108 public function getLocation()
|
Chris@12
|
109 {
|
Chris@12
|
110 return $this->location;
|
Chris@12
|
111 }
|
Chris@12
|
112
|
Chris@12
|
113 /**
|
Chris@12
|
114 * Returns whether this DocBlock is the start of a Template section.
|
Chris@12
|
115 *
|
Chris@12
|
116 * A Docblock may serve as template for a series of subsequent DocBlocks. This is indicated by a special marker
|
Chris@12
|
117 * (`#@+`) that is appended directly after the opening `/**` of a DocBlock.
|
Chris@12
|
118 *
|
Chris@12
|
119 * An example of such an opening is:
|
Chris@12
|
120 *
|
Chris@12
|
121 * ```
|
Chris@12
|
122 * /**#@+
|
Chris@12
|
123 * * My DocBlock
|
Chris@12
|
124 * * /
|
Chris@12
|
125 * ```
|
Chris@12
|
126 *
|
Chris@12
|
127 * The description and tags (not the summary!) are copied onto all subsequent DocBlocks and also applied to all
|
Chris@12
|
128 * elements that follow until another DocBlock is found that contains the closing marker (`#@-`).
|
Chris@12
|
129 *
|
Chris@12
|
130 * @see self::isTemplateEnd() for the check whether a closing marker was provided.
|
Chris@12
|
131 *
|
Chris@12
|
132 * @return boolean
|
Chris@12
|
133 */
|
Chris@12
|
134 public function isTemplateStart()
|
Chris@12
|
135 {
|
Chris@12
|
136 return $this->isTemplateStart;
|
Chris@12
|
137 }
|
Chris@12
|
138
|
Chris@12
|
139 /**
|
Chris@12
|
140 * Returns whether this DocBlock is the end of a Template section.
|
Chris@12
|
141 *
|
Chris@12
|
142 * @see self::isTemplateStart() for a more complete description of the Docblock Template functionality.
|
Chris@12
|
143 *
|
Chris@12
|
144 * @return boolean
|
Chris@12
|
145 */
|
Chris@12
|
146 public function isTemplateEnd()
|
Chris@12
|
147 {
|
Chris@12
|
148 return $this->isTemplateEnd;
|
Chris@12
|
149 }
|
Chris@12
|
150
|
Chris@12
|
151 /**
|
Chris@12
|
152 * Returns the tags for this DocBlock.
|
Chris@12
|
153 *
|
Chris@12
|
154 * @return Tag[]
|
Chris@12
|
155 */
|
Chris@12
|
156 public function getTags()
|
Chris@12
|
157 {
|
Chris@12
|
158 return $this->tags;
|
Chris@12
|
159 }
|
Chris@12
|
160
|
Chris@12
|
161 /**
|
Chris@12
|
162 * Returns an array of tags matching the given name. If no tags are found
|
Chris@12
|
163 * an empty array is returned.
|
Chris@12
|
164 *
|
Chris@12
|
165 * @param string $name String to search by.
|
Chris@12
|
166 *
|
Chris@12
|
167 * @return Tag[]
|
Chris@12
|
168 */
|
Chris@12
|
169 public function getTagsByName($name)
|
Chris@12
|
170 {
|
Chris@12
|
171 Assert::string($name);
|
Chris@12
|
172
|
Chris@12
|
173 $result = [];
|
Chris@12
|
174
|
Chris@12
|
175 /** @var Tag $tag */
|
Chris@12
|
176 foreach ($this->getTags() as $tag) {
|
Chris@12
|
177 if ($tag->getName() !== $name) {
|
Chris@12
|
178 continue;
|
Chris@12
|
179 }
|
Chris@12
|
180
|
Chris@12
|
181 $result[] = $tag;
|
Chris@12
|
182 }
|
Chris@12
|
183
|
Chris@12
|
184 return $result;
|
Chris@12
|
185 }
|
Chris@12
|
186
|
Chris@12
|
187 /**
|
Chris@12
|
188 * Checks if a tag of a certain type is present in this DocBlock.
|
Chris@12
|
189 *
|
Chris@12
|
190 * @param string $name Tag name to check for.
|
Chris@12
|
191 *
|
Chris@12
|
192 * @return bool
|
Chris@12
|
193 */
|
Chris@12
|
194 public function hasTag($name)
|
Chris@12
|
195 {
|
Chris@12
|
196 Assert::string($name);
|
Chris@12
|
197
|
Chris@12
|
198 /** @var Tag $tag */
|
Chris@12
|
199 foreach ($this->getTags() as $tag) {
|
Chris@12
|
200 if ($tag->getName() === $name) {
|
Chris@12
|
201 return true;
|
Chris@12
|
202 }
|
Chris@12
|
203 }
|
Chris@12
|
204
|
Chris@12
|
205 return false;
|
Chris@12
|
206 }
|
Chris@12
|
207
|
Chris@12
|
208 /**
|
Chris@12
|
209 * Remove a tag from this DocBlock.
|
Chris@12
|
210 *
|
Chris@12
|
211 * @param Tag $tag The tag to remove.
|
Chris@12
|
212 *
|
Chris@12
|
213 * @return void
|
Chris@12
|
214 */
|
Chris@12
|
215 public function removeTag(Tag $tagToRemove)
|
Chris@12
|
216 {
|
Chris@12
|
217 foreach ($this->tags as $key => $tag) {
|
Chris@12
|
218 if ($tag === $tagToRemove) {
|
Chris@12
|
219 unset($this->tags[$key]);
|
Chris@12
|
220 break;
|
Chris@12
|
221 }
|
Chris@12
|
222 }
|
Chris@12
|
223 }
|
Chris@12
|
224
|
Chris@12
|
225 /**
|
Chris@12
|
226 * Adds a tag to this DocBlock.
|
Chris@12
|
227 *
|
Chris@12
|
228 * @param Tag $tag The tag to add.
|
Chris@12
|
229 *
|
Chris@12
|
230 * @return void
|
Chris@12
|
231 */
|
Chris@12
|
232 private function addTag(Tag $tag)
|
Chris@12
|
233 {
|
Chris@12
|
234 $this->tags[] = $tag;
|
Chris@12
|
235 }
|
Chris@12
|
236 }
|