Skip to content

Commit 05a2534

Browse files
jrfnljrfnl
committed
Generators/HTML: don't print title if there is no content
This refactors the class to _retrieve_ the intended output, instead of echo-ing it out directly and validates whether it makes sense to print anything at all about a sniff before sending the output to screen. It deprecates the following methods, which will be removed in PHPCS 4.0: * `printHeader()` in favour of `getFormattedHeader()` * `printToc()` in favour of `getFormattedToc()` * `printFooter()` in favour of `getFormattedFooter()` * `printTextBlock()` in favour of `getFormattedTextBlock()` * `printCodeComparisonBlock()` in favour of `getFormattedCodeComparisonBlock()`
1 parent e937f98 commit 05a2534

File tree

6 files changed

+180
-228
lines changed

6 files changed

+180
-228
lines changed

‎src/Generators/HTML.php‎

Lines changed: 153 additions & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -108,95 +108,155 @@ public function generate()
108108
}
109109

110110
ob_start();
111-
$this->printHeader();
112-
$this->printToc();
113-
114111
foreach ($this->docFiles as $file) {
115112
$doc = new DOMDocument();
116113
$doc->load($file);
117114
$documentation = $doc->getElementsByTagName('documentation')->item(0);
118115
$this->processSniff($documentation);
119116
}
120117

121-
$this->printFooter();
122-
123118
$content = ob_get_contents();
124119
ob_end_clean();
125120

126-
echo $content;
121+
if (trim($content) !== '') {
122+
echo $this->getFormattedHeader();
123+
echo $this->getFormattedToc();
124+
echo $content;
125+
echo $this->getFormattedFooter();
126+
}
127127

128128
}//end generate()
129129

130130

131131
/**
132132
* Print the header of the HTML page.
133133
*
134+
* @deprecated 3.12.0 Use HTML::getFormattedHeader() instead.
135+
*
136+
* @codeCoverageIgnore
137+
*
134138
* @return void
135139
*/
136140
protected function printHeader()
137141
{
138-
$standard = $this->ruleset->name;
139-
echo '<html>'.PHP_EOL;
140-
echo ' <head>'.PHP_EOL;
141-
echo " <title>$standard Coding Standards</title>".PHP_EOL;
142-
echo ' '.str_replace("\n", PHP_EOL, self::STYLESHEET).PHP_EOL;
143-
echo ' </head>'.PHP_EOL;
144-
echo ' <body>'.PHP_EOL;
145-
echo " <h1>$standard Coding Standards</h1>".PHP_EOL;
142+
echo $this->getFormattedHeader();
146143

147144
}//end printHeader()
148145

149146

147+
/**
148+
* Format the header of the HTML page.
149+
*
150+
* @since 3.12.0 Replaces the deprecated HTML::printHeader() method.
151+
*
152+
* @return string
153+
*/
154+
protected function getFormattedHeader()
155+
{
156+
$standard = $this->ruleset->name;
157+
$output = '<html>'.PHP_EOL;
158+
$output .= ' <head>'.PHP_EOL;
159+
$output .= " <title>$standard Coding Standards</title>".PHP_EOL;
160+
$output .= ' '.str_replace("\n", PHP_EOL, self::STYLESHEET).PHP_EOL;
161+
$output .= ' </head>'.PHP_EOL;
162+
$output .= ' <body>'.PHP_EOL;
163+
$output .= " <h1>$standard Coding Standards</h1>".PHP_EOL;
164+
165+
return $output;
166+
167+
}//end getFormattedHeader()
168+
169+
150170
/**
151171
* Print the table of contents for the standard.
152172
*
153-
* The TOC is just an unordered list of bookmarks to sniffs on the page.
173+
* @deprecated 3.12.0 Use HTML::getFormattedToc() instead.
174+
*
175+
* @codeCoverageIgnore
154176
*
155177
* @return void
156178
*/
157179
protected function printToc()
180+
{
181+
echo $this->getFormattedToc();
182+
183+
}//end printToc()
184+
185+
186+
/**
187+
* Format the table of contents for the standard.
188+
*
189+
* The TOC is just an unordered list of bookmarks to sniffs on the page.
190+
*
191+
* @since 3.12.0 Replaces the deprecated HTML::printToc() method.
192+
*
193+
* @return string
194+
*/
195+
protected function getFormattedToc()
158196
{
159197
// Only show a TOC when there are two or more docs to display.
160198
if (count($this->docFiles) < 2) {
161-
return;
199+
return '';
162200
}
163201

164-
echo ' <h2>Table of Contents</h2>'.PHP_EOL;
165-
echo ' <ul class="toc">'.PHP_EOL;
202+
$output = ' <h2>Table of Contents</h2>'.PHP_EOL;
203+
$output .= ' <ul class="toc">'.PHP_EOL;
166204

167205
foreach ($this->docFiles as $file) {
168206
$doc = new DOMDocument();
169207
$doc->load($file);
170208
$documentation = $doc->getElementsByTagName('documentation')->item(0);
171209
$title = $this->getTitle($documentation);
172-
echo ' <li><a href="#'.str_replace(' ', '-', $title)."\">$title</a></li>".PHP_EOL;
210+
$output .= ' <li><a href="#'.str_replace(' ', '-', $title).'">'.$title.'</a></li>'.PHP_EOL;
173211
}
174212

175-
echo ' </ul>'.PHP_EOL;
213+
$output .= ' </ul>'.PHP_EOL;
176214

177-
}//end printToc()
215+
return $output;
216+
217+
}//end getFormattedToc()
178218

179219

180220
/**
181221
* Print the footer of the HTML page.
182222
*
223+
* @deprecated 3.12.0 Use HTML::getFormattedFooter() instead.
224+
*
225+
* @codeCoverageIgnore
226+
*
183227
* @return void
184228
*/
185229
protected function printFooter()
230+
{
231+
echo $this->getFormattedFooter();
232+
233+
}//end printFooter()
234+
235+
236+
/**
237+
* Format the footer of the HTML page.
238+
*
239+
* @since 3.12.0 Replaces the deprecated HTML::printFooter() method.
240+
*
241+
* @return string
242+
*/
243+
protected function getFormattedFooter()
186244
{
187245
// Turn off errors so we don't get timezone warnings if people
188246
// don't have their timezone set.
189247
$errorLevel = error_reporting(0);
190-
echo ' <div class="tag-line">';
191-
echo 'Documentation generated on '.date('r');
192-
echo ' by <a href="https://github.com/PHPCSStandards/PHP_CodeSniffer">PHP_CodeSniffer '.Config::VERSION.'</a>';
193-
echo '</div>'.PHP_EOL;
248+
$output = ' <div class="tag-line">';
249+
$output .= 'Documentation generated on '.date('r');
250+
$output .= ' by <a href="https://github.com/PHPCSStandards/PHP_CodeSniffer">PHP_CodeSniffer '.Config::VERSION.'</a>';
251+
$output .= '</div>'.PHP_EOL;
194252
error_reporting($errorLevel);
195253

196-
echo ' </body>'.PHP_EOL;
197-
echo '</html>'.PHP_EOL;
254+
$output .= ' </body>'.PHP_EOL;
255+
$output .= '</html>'.PHP_EOL;
198256

199-
}//end printFooter()
257+
return $output;
258+
259+
}//end getFormattedFooter()
200260

201261

202262
/**
@@ -210,18 +270,22 @@ protected function printFooter()
210270
*/
211271
public function processSniff(DOMNode $doc)
212272
{
213-
$title = $this->getTitle($doc);
214-
echo ' <a name="'.str_replace(' ', '-', $title).'" />'.PHP_EOL;
215-
echo " <h2>$title</h2>".PHP_EOL;
216-
273+
$content = '';
217274
foreach ($doc->childNodes as $node) {
218275
if ($node->nodeName === 'standard') {
219-
$this->printTextBlock($node);
276+
$content .= $this->getFormattedTextBlock($node);
220277
} else if ($node->nodeName === 'code_comparison') {
221-
$this->printCodeComparisonBlock($node);
278+
$content .= $this->getFormattedCodeComparisonBlock($node);
222279
}
223280
}
224281

282+
if (trim($content) !== '') {
283+
$title = $this->getTitle($doc);
284+
echo ' <a name="'.str_replace(' ', '-', $title).'" />'.PHP_EOL;
285+
echo ' <h2>'.$title.'</h2>'.PHP_EOL;
286+
echo $content;
287+
}
288+
225289
}//end processSniff()
226290

227291

@@ -230,9 +294,29 @@ public function processSniff(DOMNode $doc)
230294
*
231295
* @param \DOMNode $node The DOMNode object for the text block.
232296
*
297+
* @deprecated 3.12.0 Use HTML::getFormattedTextBlock() instead.
298+
*
299+
* @codeCoverageIgnore
300+
*
233301
* @return void
234302
*/
235303
protected function printTextBlock(DOMNode $node)
304+
{
305+
echo $this->getFormattedTextBlock($node);
306+
307+
}//end printTextBlock()
308+
309+
310+
/**
311+
* Format a text block found in a standard.
312+
*
313+
* @param \DOMNode $node The DOMNode object for the text block.
314+
*
315+
* @since 3.12.0 Replaces the deprecated HTML::printTextBlock() method.
316+
*
317+
* @return string
318+
*/
319+
protected function getFormattedTextBlock(DOMNode $node)
236320
{
237321
$content = trim($node->nodeValue);
238322
$content = htmlspecialchars($content, (ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML401));
@@ -265,19 +349,39 @@ protected function printTextBlock(DOMNode $node)
265349
}
266350
}
267351

268-
echo ' <p class="text">'.implode('', $lines).'</p>'.PHP_EOL;
352+
return ' <p class="text">'.implode('', $lines).'</p>'.PHP_EOL;
269353

270-
}//end printTextBlock()
354+
}//end getFormattedTextBlock()
271355

272356

273357
/**
274358
* Print a code comparison block found in a standard.
275359
*
276360
* @param \DOMNode $node The DOMNode object for the code comparison block.
277361
*
362+
* @deprecated 3.12.0 Use HTML::getFormattedCodeComparisonBlock() instead.
363+
*
364+
* @codeCoverageIgnore
365+
*
278366
* @return void
279367
*/
280368
protected function printCodeComparisonBlock(DOMNode $node)
369+
{
370+
echo $this->getFormattedCodeComparisonBlock($node);
371+
372+
}//end printCodeComparisonBlock()
373+
374+
375+
/**
376+
* Format a code comparison block found in a standard.
377+
*
378+
* @param \DOMNode $node The DOMNode object for the code comparison block.
379+
*
380+
* @since 3.12.0 Replaces the deprecated HTML::printCodeComparisonBlock() method.
381+
*
382+
* @return string
383+
*/
384+
protected function getFormattedCodeComparisonBlock(DOMNode $node)
281385
{
282386
$codeBlocks = $node->getElementsByTagName('code');
283387

@@ -299,18 +403,20 @@ protected function printCodeComparisonBlock(DOMNode $node)
299403
$second = str_replace('<em>', '<span class="code-comparison-highlight">', $second);
300404
$second = str_replace('</em>', '</span>', $second);
301405

302-
echo ' <table class="code-comparison">'.PHP_EOL;
303-
echo ' <tr>'.PHP_EOL;
304-
echo " <td class=\"code-comparison-title\">$firstTitle</td>".PHP_EOL;
305-
echo " <td class=\"code-comparison-title\">$secondTitle</td>".PHP_EOL;
306-
echo ' </tr>'.PHP_EOL;
307-
echo ' <tr>'.PHP_EOL;
308-
echo " <td class=\"code-comparison-code\">$first</td>".PHP_EOL;
309-
echo " <td class=\"code-comparison-code\">$second</td>".PHP_EOL;
310-
echo ' </tr>'.PHP_EOL;
311-
echo ' </table>'.PHP_EOL;
406+
$output = ' <table class="code-comparison">'.PHP_EOL;
407+
$output .= ' <tr>'.PHP_EOL;
408+
$output .= " <td class=\"code-comparison-title\">$firstTitle</td>".PHP_EOL;
409+
$output .= " <td class=\"code-comparison-title\">$secondTitle</td>".PHP_EOL;
410+
$output .= ' </tr>'.PHP_EOL;
411+
$output .= ' <tr>'.PHP_EOL;
412+
$output .= " <td class=\"code-comparison-code\">$first</td>".PHP_EOL;
413+
$output .= " <td class=\"code-comparison-code\">$second</td>".PHP_EOL;
414+
$output .= ' </tr>'.PHP_EOL;
415+
$output .= ' </table>'.PHP_EOL;
312416

313-
}//end printCodeComparisonBlock()
417+
return $output;
418+
419+
}//end getFormattedCodeComparisonBlock()
314420

315421

316422
}//end class

‎tests/Core/Generators/Expectations/ExpectedOutputStructureDocs.html‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -81,8 +81,6 @@ <h2>Table of Contents</h2>
8181
<li><a href="#Two-Standard-Blocks,-One-Code-Comparison">Two Standard Blocks, One Code Comparison</a></li>
8282
<li><a href="#Two-Standard-Blocks,-Three-Code-Comparisons">Two Standard Blocks, Three Code Comparisons</a></li>
8383
</ul>
84-
<a name="No-Content" />
85-
<h2>No Content</h2>
8684
<a name="Code-Comparison-Only,-Missing-Standard-Block" />
8785
<h2>Code Comparison Only, Missing Standard Block</h2>
8886
<table class="code-comparison">

0 commit comments

Comments
 (0)