[TASK] Streamline phpdoc annotations in EXT:extbase
[Packages/TYPO3.CMS.git] / typo3 / sysext / extbase / Classes / Reflection / DocCommentParser.php
1 <?php
2 namespace TYPO3\CMS\Extbase\Reflection;
3
4 /*
5 * This file is part of the TYPO3 CMS project.
6 *
7 * It is free software; you can redistribute it and/or modify it under
8 * the terms of the GNU General Public License, either version 2
9 * of the License, or any later version.
10 *
11 * For the full copyright and license information, please read the
12 * LICENSE.txt file that was distributed with this source code.
13 *
14 * The TYPO3 project - inspiring people to share!
15 */
16
17 /**
18 * A little parser which creates tag objects from doc comments
19 * @internal only to be used within Extbase, not part of TYPO3 Core API.
20 */
21 class DocCommentParser
22 {
23 /**
24 * @var array
25 */
26 protected static $ignoredTags = ['package', 'subpackage', 'license', 'copyright', 'author', 'version', 'const'];
27
28 /**
29 * @var string The description as found in the doc comment
30 */
31 protected $description = '';
32
33 /**
34 * @var array An array of tag names and their values (multiple values are possible)
35 */
36 protected $tags = [];
37
38 /**
39 * @var bool
40 */
41 private $useIgnoredTags;
42
43 /**
44 * @param bool $useIgnoredTags
45 */
46 public function __construct($useIgnoredTags = false)
47 {
48 $this->useIgnoredTags = $useIgnoredTags;
49 }
50
51 /**
52 * Parses the given doc comment and saves the result (description and
53 * tags) in the parser's object. They can be retrieved by the
54 * getTags() getTagValues() and getDescription() methods.
55 *
56 * @param string $docComment A doc comment as returned by the reflection getDocComment() method
57 */
58 public function parseDocComment($docComment)
59 {
60 $this->description = '';
61 $this->tags = [];
62 $lines = explode(LF, $docComment);
63 foreach ($lines as $line) {
64 if ($line !== '' && strpos($line, '@') !== false) {
65 $this->parseTag(substr($line, strpos($line, '@')));
66 } elseif (empty($this->tags)) {
67 $this->description .= preg_replace('#\\s*/?[*/]*(.*)$#', '$1', $line) . LF;
68 }
69 }
70 $this->description = trim($this->description);
71 }
72
73 /**
74 * Returns the tags which have been previously parsed
75 *
76 * @return array Array of tag names and their (multiple) values
77 */
78 public function getTagsValues()
79 {
80 return $this->tags;
81 }
82
83 /**
84 * Returns the values of the specified tag. The doc comment
85 * must be parsed with parseDocComment() before tags are
86 * available.
87 *
88 * @param string $tagName The tag name to retrieve the values for
89 * @throws \RuntimeException
90 * @return array The tag's values
91 */
92 public function getTagValues($tagName)
93 {
94 if (!$this->isTaggedWith($tagName)) {
95 throw new \RuntimeException('Tag "' . $tagName . '" does not exist.', 1169128255);
96 }
97 return $this->tags[$tagName];
98 }
99
100 /**
101 * Checks if a tag with the given name exists
102 *
103 * @param string $tagName The tag name to check for
104 * @return bool TRUE the tag exists, otherwise FALSE
105 */
106 public function isTaggedWith($tagName)
107 {
108 return isset($this->tags[$tagName]);
109 }
110
111 /**
112 * Returns the description which has been previously parsed
113 *
114 * @return string The description which has been parsed
115 */
116 public function getDescription()
117 {
118 return $this->description;
119 }
120
121 /**
122 * Parses a line of a doc comment for a tag and its value.
123 * The result is stored in the interal tags array.
124 *
125 * @param string $line A line of a doc comment which starts with an @-sign
126 */
127 protected function parseTag($line)
128 {
129 $tagAndValue = preg_split('/\\s/', $line, 2);
130 $tag = substr($tagAndValue[0], 1);
131
132 if ($this->useIgnoredTags && in_array($tag, static::$ignoredTags, true)) {
133 return;
134 }
135
136 if (count($tagAndValue) > 1) {
137 $this->tags[$tag][] = trim($tagAndValue[1]);
138 } else {
139 $this->tags[$tag] = [];
140 }
141 }
142 }