These results are based on our legacy PHP analysis, consider migrating to our new PHP analysis engine instead. Learn more
1 | <?php |
||
2 | declare(strict_types=1); |
||
3 | |||
4 | /** |
||
5 | * This file is part of phpDocumentor. |
||
6 | * |
||
7 | * For the full copyright and license information, please view the LICENSE |
||
8 | * file that was distributed with this source code. |
||
9 | * |
||
10 | * @author Mike van Riel <[email protected]> |
||
11 | * @copyright 2010-2018 Mike van Riel / Naenius (http://www.naenius.com) |
||
12 | * @license http://www.opensource.org/licenses/mit-license.php MIT |
||
13 | * @link http://phpdoc.org |
||
14 | */ |
||
15 | |||
16 | namespace phpDocumentor\Transformer\Behaviour\Tag; |
||
17 | |||
18 | /** |
||
19 | * Behaviour that adds support for the @covers tag |
||
20 | */ |
||
21 | class CoversTag |
||
22 | { |
||
23 | /** |
||
24 | * Find all return tags that contain 'self' or '$this' and replace those |
||
25 | * terms for the name of the current class' type. |
||
26 | * |
||
27 | * @param \DOMDocument $xml Structure source to apply behaviour onto. |
||
28 | * |
||
29 | * @todo split method into submethods |
||
30 | * |
||
31 | * @return \DOMDocument |
||
32 | */ |
||
33 | public function process(\DOMDocument $xml) |
||
34 | { |
||
35 | $xpath = new \DOMXPath($xml); |
||
36 | $nodes = $xpath->query('//tag[@name=\'covers\']'); |
||
37 | |||
38 | /** @var \DOMElement $node */ |
||
39 | foreach ($nodes as $node) { |
||
40 | $refers = $node->getAttribute('refers'); |
||
41 | $refers_array = explode('::', $refers); |
||
42 | |||
43 | // determine the type so we know where to put the @coveredby tag on |
||
44 | $type = 'class'; |
||
45 | if (isset($refers_array[1])) { |
||
46 | // starts with $ = property, ends with () = method, |
||
47 | // otherwise constant |
||
48 | $type = $refers_array[1][0] === '$' ? 'property' : 'constant'; |
||
49 | $type = substr($refers_array[1], -2) === '()' ? 'method' : $type; |
||
50 | } |
||
51 | |||
52 | switch ($type) { |
||
53 | case 'class': |
||
54 | // escape single quotes in the class name |
||
55 | $xpath_refers = 'concat(\'' . str_replace( |
||
56 | ["'", '"'], |
||
57 | ['\', "\'", \'', '\', \'"\' , \''], |
||
58 | $refers |
||
59 | ) . "', '')"; |
||
60 | |||
61 | $qry = '/project/file/class[full_name=' . $xpath_refers . ']'; |
||
62 | break; |
||
63 | default: |
||
64 | $class_name = $refers_array[0]; |
||
65 | |||
66 | // escape single quotes in the class name |
||
67 | $xpath_class_name = 'concat(\'' . str_replace( |
||
68 | ["'", '"'], |
||
69 | ['\', "\'", \'', '\', \'"\' , \''], |
||
70 | $class_name |
||
71 | ) . "', '')"; |
||
72 | |||
73 | // escape single quotes in the method name |
||
74 | $xpath_method_name = 'concat(\'' . str_replace( |
||
75 | ["'", '"'], |
||
76 | ['\', "\'", \'', '\', \'"\' , \''], |
||
77 | rtrim($refers_array[1], '()') |
||
78 | ) . "', '')"; |
||
79 | |||
80 | $qry = '/project/file/class[full_name=' . $xpath_class_name |
||
81 | . ']/' . $type . '[name=' . $xpath_method_name . ']'; |
||
82 | break; |
||
83 | } |
||
84 | |||
85 | /** @noinspection PhpUsageOfSilenceOperatorInspection as there is no pre-validation possible */ |
||
86 | $referral_nodes = @$xpath->query($qry); |
||
87 | |||
88 | // if the query is wrong; output a Critical error and continue to |
||
89 | // the next @covers |
||
90 | if ($referral_nodes === false) { |
||
91 | // $this->log( |
||
92 | // 'An XPath error occurs while processing @covers, the query used was: ' . $qry, |
||
0 ignored issues
–
show
|
|||
93 | // LogLevel::CRITICAL |
||
94 | // ); |
||
95 | continue; |
||
96 | } |
||
97 | |||
98 | // check if the result is unique; if not we error and continue |
||
99 | // to the next @covers |
||
100 | if ($referral_nodes->length > 1) { |
||
101 | continue; |
||
102 | } |
||
103 | |||
104 | // if there is one matching element; link them together |
||
105 | if ($referral_nodes->length > 0) { |
||
106 | /** @var \DOMElement $referral */ |
||
107 | $referral = $referral_nodes->item(0); |
||
108 | $docblock = $referral->getElementsByTagName('docblock'); |
||
109 | if ($docblock->length < 1) { |
||
110 | $docblock = new \DOMElement('docblock'); |
||
111 | $referral->appendChild($docblock); |
||
112 | } else { |
||
113 | $docblock = $docblock->item(0); |
||
114 | } |
||
115 | |||
116 | $used_by = new \DOMElement('tag'); |
||
117 | $docblock->appendChild($used_by); |
||
118 | $used_by->setAttribute('name', 'used_by'); |
||
119 | $used_by->setAttribute('line', ''); |
||
120 | |||
121 | // gather the name of the referring element and set that as refers |
||
122 | // attribute |
||
123 | if ($node->parentNode->parentNode->nodeName === 'class') { |
||
124 | // if the element where the @covers is in is a class; nothing |
||
125 | // more than the class name need to returned |
||
126 | |||
127 | /** @var \DOMElement $grandParentNode */ |
||
128 | $grandParentNode = $node->parentNode->parentNode; |
||
129 | $referral_name = $grandParentNode |
||
130 | ->getElementsByTagName('full_name')->item(0)->nodeValue; |
||
131 | } else { |
||
132 | $referral_class_name = null; |
||
133 | if ($node->parentNode->parentNode->nodeName === 'method') { |
||
134 | // gather the name of the class where the @covers is in |
||
135 | |||
136 | /** @var \DOMElement $greatGrandParentNode */ |
||
137 | $greatGrandParentNode = $node->parentNode->parentNode->parentNode; |
||
138 | $referral_class_name = $greatGrandParentNode |
||
139 | ->getElementsByTagName('full_name')->item(0) |
||
140 | ->nodeValue; |
||
141 | } |
||
142 | |||
143 | // gather the name of the subelement of the class where |
||
144 | // the @covers is in |
||
145 | |||
146 | /** @var \DOMElement $grandParentNode */ |
||
147 | $grandParentNode = $node->parentNode->parentNode; |
||
148 | $referral_name = $grandParentNode |
||
149 | ->getElementsByTagName('name')->item(0)->nodeValue; |
||
150 | |||
151 | // if it is a method; suffix with () |
||
152 | if ($node->parentNode->parentNode->nodeName === 'method' |
||
153 | || $node->parentNode->parentNode->nodeName === 'function' |
||
154 | ) { |
||
155 | $referral_name .= '()'; |
||
156 | } |
||
157 | |||
158 | // only prefix class name if this is a class member |
||
159 | if ($referral_class_name) { |
||
160 | $referral_name = $referral_class_name . '::' |
||
161 | . $referral_name; |
||
162 | } |
||
163 | } |
||
164 | |||
165 | $used_by->setAttribute('description', $referral_name); |
||
166 | $used_by->setAttribute('refers', $referral_name); |
||
167 | } |
||
168 | } |
||
169 | |||
170 | return $xml; |
||
171 | } |
||
172 | } |
||
173 |
Sometimes obsolete code just ends up commented out instead of removed. In this case it is better to remove the code once you have checked you do not need it.
The code might also have been commented out for debugging purposes. In this case it is vital that someone uncomments it again or your project may behave in very unexpected ways in production.
This check looks for comments that seem to be mostly valid code and reports them.