7 * @author Mike van Riel <mike.vanriel@naenius.com>
8 * @copyright 2010-2011 Mike van Riel / Naenius (http://www.naenius.com)
9 * @license http://www.opensource.org/licenses/mit-license.php MIT
10 * @link http://phpdoc.org
13 namespace phpDocumentor\Reflection;
15 use phpDocumentor\Reflection\DocBlock\Tag;
16 use phpDocumentor\Reflection\DocBlock\Context;
17 use phpDocumentor\Reflection\DocBlock\Location;
20 * Parses the DocBlock for any structure.
22 * @author Mike van Riel <mike.vanriel@naenius.com>
23 * @license http://www.opensource.org/licenses/mit-license.php MIT
24 * @link http://phpdoc.org
26 class DocBlock implements \Reflector
28 /** @var string The opening line for this docblock. */
29 protected $short_description = '';
32 * @var DocBlock\Description The actual
33 * description for this docblock.
35 protected $long_description = null;
38 * @var Tag[] An array containing all
39 * the tags in this docblock; except inline.
41 protected $tags = array();
43 /** @var Context Information about the context of this DocBlock. */
44 protected $context = null;
46 /** @var Location Information about the location of this DocBlock. */
47 protected $location = null;
49 /** @var bool Is this DocBlock (the start of) a template? */
50 protected $isTemplateStart = false;
52 /** @var bool Does this DocBlock signify the end of a DocBlock template? */
53 protected $isTemplateEnd = false;
56 * Parses the given docblock and populates the member fields.
58 * The constructor may also receive namespace information such as the
59 * current namespace and aliases. This information is used by some tags
60 * (e.g. @return, @param, etc.) to turn a relative Type into a FQCN.
62 * @param \Reflector|string $docblock A docblock comment (including
63 * asterisks) or reflector supporting the getDocComment method.
64 * @param Context $context The context in which the DocBlock
66 * @param Location $location The location within the file that this
69 * @throws \InvalidArgumentException if the given argument does not have the
70 * getDocComment method.
72 public function __construct(
74 Context $context = null,
75 Location $location = null
77 if (is_object($docblock)) {
78 if (!method_exists($docblock, 'getDocComment')) {
79 throw new \InvalidArgumentException(
80 'Invalid object passed; the given reflector must support '
81 . 'the getDocComment method'
85 $docblock = $docblock->getDocComment();
88 $docblock = $this->cleanInput($docblock);
90 list($templateMarker, $short, $long, $tags) = $this->splitDocBlock($docblock);
91 $this->isTemplateStart = $templateMarker === '#@+';
92 $this->isTemplateEnd = $templateMarker === '#@-';
93 $this->short_description = $short;
94 $this->long_description = new DocBlock\Description($long, $this);
95 $this->parseTags($tags);
97 $this->context = $context;
98 $this->location = $location;
102 * Strips the asterisks from the DocBlock comment.
104 * @param string $comment String containing the comment text.
108 protected function cleanInput($comment)
112 '#[ \t]*(?:\/\*\*|\*\/|\*)?[ \t]{0,1}(.*)?#u',
118 // reg ex above is not able to remove */ from a single line docblock
119 if (substr($comment, -2) == '*/') {
120 $comment = trim(substr($comment, 0, -2));
124 $comment = str_replace(array("\r\n", "\r"), "\n", $comment);
130 * Splits the DocBlock into a template marker, summary, description and block of tags.
132 * @param string $comment Comment to split into the sub-parts.
134 * @author Richard van Velzen (@_richardJ) Special thanks to Richard for the regex responsible for the split.
135 * @author Mike van Riel <me@mikevanriel.com> for extending the regex with template marker support.
137 * @return string[] containing the template marker (if any), summary, description and a string containing the tags.
139 protected function splitDocBlock($comment)
141 // Performance improvement cheat: if the first character is an @ then only tags are in this DocBlock. This
142 // method does not split tags so we return this verbatim as the fourth result (tags). This saves us the
143 // performance impact of running a regular expression
144 if (strpos($comment, '@') === 0) {
145 return array('', '', '', $comment);
148 // clears all extra horizontal whitespace from the line endings to prevent parsing issues
149 $comment = preg_replace('/\h*$/Sum', '', $comment);
152 * Splits the docblock into a template marker, short description, long description and tags section
154 * - The template marker is empty, #@+ or #@- if the DocBlock starts with either of those (a newline may
155 * occur after it and will be stripped).
156 * - The short description is started from the first character until a dot is encountered followed by a
157 * newline OR two consecutive newlines (horizontal whitespace is taken into account to consider spacing
158 * errors). This is optional.
159 * - The long description, any character until a new line is encountered followed by an @ and word
160 * characters (a tag). This is optional.
161 * - Tags; the remaining characters
163 * Big thanks to RichardJ for contributing this Regular Expression
168 # 1. Extract the template marker
169 (?:(\#\@\+|\#\@\-)\n?)?
171 # 2. Extract the summary
173 (?! @\pL ) # The summary may not start with an @
177 (?! \. \n | \n{2} ) # End summary upon a dot followed by newline or two newlines
178 [\n.] (?! [ \t]* @\pL ) # End summary when an @ is found as first character on a new line
179 [^\n.]+ # Include anything else
185 # 3. Extract the description
187 \s* # Some form of whitespace _must_ precede a description because a summary must be there
188 (?! @\pL ) # The description may not start with an @
192 (?! [ \t]* @\pL ) # End description when an @ is found as first character on a new line
193 [^\n]+ # Include anything else
198 # 4. Extract the tags (anything that follows)
199 (\s+ [\s\S]*)? # everything that follows
204 array_shift($matches);
206 while (count($matches) < 4) {
214 * Creates the tag objects.
216 * @param string $tags Tag block to parse.
220 protected function parseTags($tags)
225 if ('@' !== $tags[0]) {
226 throw new \LogicException(
227 'A tag block started with text instead of an actual tag,'
228 . ' this makes the tag block invalid: ' . $tags
231 foreach (explode("\n", $tags) as $tag_line) {
232 if (isset($tag_line[0]) && ($tag_line[0] === '@')) {
233 $result[] = $tag_line;
235 $result[count($result) - 1] .= "\n" . $tag_line;
239 // create proper Tag objects
240 foreach ($result as $key => $tag_line) {
241 $result[$key] = Tag::createInstance(trim($tag_line), $this);
245 $this->tags = $result;
249 * Gets the text portion of the doc block.
251 * Gets the text portion (short and long description combined) of the doc
254 * @return string The text portion of the doc block.
256 public function getText()
258 $short = $this->getShortDescription();
259 $long = $this->getLongDescription()->getContents();
262 return "{$short}\n\n{$long}";
269 * Set the text portion of the doc block.
271 * Sets the text portion (short and long description combined) of the doc
274 * @param string $docblock The new text portion of the doc block.
276 * @return $this This doc block.
278 public function setText($comment)
280 list(,$short, $long) = $this->splitDocBlock($comment);
281 $this->short_description = $short;
282 $this->long_description = new DocBlock\Description($long, $this);
286 * Returns the opening line or also known as short description.
290 public function getShortDescription()
292 return $this->short_description;
296 * Returns the full description or also known as long description.
298 * @return DocBlock\Description
300 public function getLongDescription()
302 return $this->long_description;
306 * Returns whether this DocBlock is the start of a Template section.
308 * A Docblock may serve as template for a series of subsequent DocBlocks. This is indicated by a special marker
309 * (`#@+`) that is appended directly after the opening `/**` of a DocBlock.
311 * An example of such an opening is:
319 * The description and tags (not the summary!) are copied onto all subsequent DocBlocks and also applied to all
320 * elements that follow until another DocBlock is found that contains the closing marker (`#@-`).
322 * @see self::isTemplateEnd() for the check whether a closing marker was provided.
326 public function isTemplateStart()
328 return $this->isTemplateStart;
332 * Returns whether this DocBlock is the end of a Template section.
334 * @see self::isTemplateStart() for a more complete description of the Docblock Template functionality.
338 public function isTemplateEnd()
340 return $this->isTemplateEnd;
344 * Returns the current context.
348 public function getContext()
350 return $this->context;
354 * Returns the current location.
358 public function getLocation()
360 return $this->location;
364 * Returns the tags for this DocBlock.
368 public function getTags()
374 * Returns an array of tags matching the given name. If no tags are found
375 * an empty array is returned.
377 * @param string $name String to search by.
381 public function getTagsByName($name)
386 foreach ($this->getTags() as $tag) {
387 if ($tag->getName() != $name) {
398 * Checks if a tag of a certain type is present in this DocBlock.
400 * @param string $name Tag name to check for.
404 public function hasTag($name)
407 foreach ($this->getTags() as $tag) {
408 if ($tag->getName() == $name) {
417 * Appends a tag at the end of the list of tags.
419 * @param Tag $tag The tag to add.
421 * @return Tag The newly added tag.
423 * @throws \LogicException When the tag belongs to a different DocBlock.
425 public function appendTag(Tag $tag)
427 if (null === $tag->getDocBlock()) {
428 $tag->setDocBlock($this);
431 if ($tag->getDocBlock() === $this) {
432 $this->tags[] = $tag;
434 throw new \LogicException(
435 'This tag belongs to a different DocBlock object.'
444 * Builds a string representation of this object.
446 * @todo determine the exact format as used by PHP Reflection and
450 * @codeCoverageIgnore Not yet implemented
452 public static function export()
454 throw new \Exception('Not yet implemented');
458 * Returns the exported information (we should use the export static method
459 * BUT this throws an exception at this point).
462 * @codeCoverageIgnore Not yet implemented
464 public function __toString()
466 return 'Not yet implemented';