Skip to content

Commit

Permalink
Generators/HTML: don't print title if there is no content
Browse files Browse the repository at this point in the history 
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()`
  • Loading branch information
@jrfnl
jrfnl committed Jan 23, 2025
1 parent 6ebb1dd commit cc82dcd
Show file tree
Hide file tree
Showing 6 changed files with 180 additions and 228 deletions.
200 changes: 153 additions & 47 deletions src/Generators/HTML.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -108,95 +108,155 @@ public function generate()
}

ob_start();
$this->printHeader();
$this->printToc();

foreach ($this->docFiles as $file) {
$doc = new DOMDocument();
$doc->load($file);
$documentation = $doc->getElementsByTagName('documentation')->item(0);
$this->processSniff($documentation);
}

$this->printFooter();

$content = ob_get_contents();
ob_end_clean();

echo $content;
if (trim($content) !== '') {
echo $this->getFormattedHeader();
echo $this->getFormattedToc();
echo $content;
echo $this->getFormattedFooter();
}

}//end generate()


/**
* Print the header of the HTML page.
*
* @deprecated 3.12.0 Use HTML::getFormattedHeader() instead.
*
* @codeCoverageIgnore
*
* @return void
*/
protected function printHeader()
{
$standard = $this->ruleset->name;
echo '<html>'.PHP_EOL;
echo ' <head>'.PHP_EOL;
echo " <title>$standard Coding Standards</title>".PHP_EOL;
echo ' '.str_replace("\n", PHP_EOL, self::STYLESHEET).PHP_EOL;
echo ' </head>'.PHP_EOL;
echo ' <body>'.PHP_EOL;
echo " <h1>$standard Coding Standards</h1>".PHP_EOL;
echo $this->getFormattedHeader();

}//end printHeader()


/**
* Format the header of the HTML page.
*
* @since 3.12.0 Replaces the deprecated HTML::printHeader() method.
*
* @return string
*/
protected function getFormattedHeader()
{
$standard = $this->ruleset->name;
$output = '<html>'.PHP_EOL;
$output .= ' <head>'.PHP_EOL;
$output .= " <title>$standard Coding Standards</title>".PHP_EOL;
$output .= ' '.str_replace("\n", PHP_EOL, self::STYLESHEET).PHP_EOL;
$output .= ' </head>'.PHP_EOL;
$output .= ' <body>'.PHP_EOL;
$output .= " <h1>$standard Coding Standards</h1>".PHP_EOL;

return $output;

}//end getFormattedHeader()


/**
* Print the table of contents for the standard.
*
* The TOC is just an unordered list of bookmarks to sniffs on the page.
* @deprecated 3.12.0 Use HTML::getFormattedToc() instead.
*
* @codeCoverageIgnore
*
* @return void
*/
protected function printToc()
{
echo $this->getFormattedToc();

}//end printToc()


/**
* Format the table of contents for the standard.
*
* The TOC is just an unordered list of bookmarks to sniffs on the page.
*
* @since 3.12.0 Replaces the deprecated HTML::printToc() method.
*
* @return string
*/
protected function getFormattedToc()
{
// Only show a TOC when there are two or more docs to display.
if (count($this->docFiles) < 2) {
return;
return '';
}

echo ' <h2>Table of Contents</h2>'.PHP_EOL;
echo ' <ul class="toc">'.PHP_EOL;
$output = ' <h2>Table of Contents</h2>'.PHP_EOL;
$output .= ' <ul class="toc">'.PHP_EOL;

foreach ($this->docFiles as $file) {
$doc = new DOMDocument();
$doc->load($file);
$documentation = $doc->getElementsByTagName('documentation')->item(0);
$title = $this->getTitle($documentation);
echo ' <li><a href="#'.str_replace(' ', '-', $title)."\">$title</a></li>".PHP_EOL;
$output .= ' <li><a href="#'.str_replace(' ', '-', $title).'">'.$title.'</a></li>'.PHP_EOL;
}

echo ' </ul>'.PHP_EOL;
$output .= ' </ul>'.PHP_EOL;

}//end printToc()
return $output;

}//end getFormattedToc()


/**
* Print the footer of the HTML page.
*
* @deprecated 3.12.0 Use HTML::getFormattedFooter() instead.
*
* @codeCoverageIgnore
*
* @return void
*/
protected function printFooter()
{
echo $this->getFormattedFooter();

}//end printFooter()


/**
* Format the footer of the HTML page.
*
* @since 3.12.0 Replaces the deprecated HTML::printFooter() method.
*
* @return string
*/
protected function getFormattedFooter()
{
// Turn off errors so we don't get timezone warnings if people
// don't have their timezone set.
$errorLevel = error_reporting(0);
echo ' <div class="tag-line">';
echo 'Documentation generated on '.date('r');
echo ' by <a href="https://github.com/PHPCSStandards/PHP_CodeSniffer">PHP_CodeSniffer '.Config::VERSION.'</a>';
echo '</div>'.PHP_EOL;
$output = ' <div class="tag-line">';
$output .= 'Documentation generated on '.date('r');
$output .= ' by <a href="https://github.com/PHPCSStandards/PHP_CodeSniffer">PHP_CodeSniffer '.Config::VERSION.'</a>';
$output .= '</div>'.PHP_EOL;
error_reporting($errorLevel);

echo ' </body>'.PHP_EOL;
echo '</html>'.PHP_EOL;
$output .= ' </body>'.PHP_EOL;
$output .= '</html>'.PHP_EOL;

}//end printFooter()
return $output;

}//end getFormattedFooter()


/**
Expand All @@ -210,18 +270,22 @@ protected function printFooter()
*/
public function processSniff(DOMNode $doc)
{
$title = $this->getTitle($doc);
echo ' <a name="'.str_replace(' ', '-', $title).'" />'.PHP_EOL;
echo " <h2>$title</h2>".PHP_EOL;

$content = '';
foreach ($doc->childNodes as $node) {
if ($node->nodeName === 'standard') {
$this->printTextBlock($node);
$content .= $this->getFormattedTextBlock($node);
} else if ($node->nodeName === 'code_comparison') {
$this->printCodeComparisonBlock($node);
$content .= $this->getFormattedCodeComparisonBlock($node);
}
}

if (trim($content) !== '') {
$title = $this->getTitle($doc);
echo ' <a name="'.str_replace(' ', '-', $title).'" />'.PHP_EOL;
echo ' <h2>'.$title.'</h2>'.PHP_EOL;
echo $content;
}

}//end processSniff()


Expand All @@ -230,9 +294,29 @@ public function processSniff(DOMNode $doc)
*
* @param \DOMNode $node The DOMNode object for the text block.
*
* @deprecated 3.12.0 Use HTML::getFormattedTextBlock() instead.
*
* @codeCoverageIgnore
*
* @return void
*/
protected function printTextBlock(DOMNode $node)
{
echo $this->getFormattedTextBlock($node);

}//end printTextBlock()


/**
* Format a text block found in a standard.
*
* @param \DOMNode $node The DOMNode object for the text block.
*
* @since 3.12.0 Replaces the deprecated HTML::printTextBlock() method.
*
* @return string
*/
protected function getFormattedTextBlock(DOMNode $node)
{
$content = trim($node->nodeValue);
$content = htmlspecialchars($content, (ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML401));
Expand Down Expand Up @@ -265,19 +349,39 @@ protected function printTextBlock(DOMNode $node)
}
}

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

}//end printTextBlock()
}//end getFormattedTextBlock()


/**
* Print a code comparison block found in a standard.
*
* @param \DOMNode $node The DOMNode object for the code comparison block.
*
* @deprecated 3.12.0 Use HTML::getFormattedCodeComparisonBlock() instead.
*
* @codeCoverageIgnore
*
* @return void
*/
protected function printCodeComparisonBlock(DOMNode $node)
{
echo $this->getFormattedCodeComparisonBlock($node);

}//end printCodeComparisonBlock()


/**
* Format a code comparison block found in a standard.
*
* @param \DOMNode $node The DOMNode object for the code comparison block.
*
* @since 3.12.0 Replaces the deprecated HTML::printCodeComparisonBlock() method.
*
* @return string
*/
protected function getFormattedCodeComparisonBlock(DOMNode $node)
{
$codeBlocks = $node->getElementsByTagName('code');

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

echo ' <table class="code-comparison">'.PHP_EOL;
echo ' <tr>'.PHP_EOL;
echo " <td class=\"code-comparison-title\">$firstTitle</td>".PHP_EOL;
echo " <td class=\"code-comparison-title\">$secondTitle</td>".PHP_EOL;
echo ' </tr>'.PHP_EOL;
echo ' <tr>'.PHP_EOL;
echo " <td class=\"code-comparison-code\">$first</td>".PHP_EOL;
echo " <td class=\"code-comparison-code\">$second</td>".PHP_EOL;
echo ' </tr>'.PHP_EOL;
echo ' </table>'.PHP_EOL;
$output = ' <table class="code-comparison">'.PHP_EOL;
$output .= ' <tr>'.PHP_EOL;
$output .= " <td class=\"code-comparison-title\">$firstTitle</td>".PHP_EOL;
$output .= " <td class=\"code-comparison-title\">$secondTitle</td>".PHP_EOL;
$output .= ' </tr>'.PHP_EOL;
$output .= ' <tr>'.PHP_EOL;
$output .= " <td class=\"code-comparison-code\">$first</td>".PHP_EOL;
$output .= " <td class=\"code-comparison-code\">$second</td>".PHP_EOL;
$output .= ' </tr>'.PHP_EOL;
$output .= ' </table>'.PHP_EOL;

}//end printCodeComparisonBlock()
return $output;

}//end getFormattedCodeComparisonBlock()


}//end class
2 changes: 0 additions & 2 deletions tests/Core/Generators/Expectations/ExpectedOutputStructureDocs.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -81,8 +81,6 @@ <h2>Table of Contents</h2>
<li><a href="#Two-Standard-Blocks,-One-Code-Comparison">Two Standard Blocks, One Code Comparison</a></li>
<li><a href="#Two-Standard-Blocks,-Three-Code-Comparisons">Two Standard Blocks, Three Code Comparisons</a></li>
</ul>
<a name="No-Content" />
<h2>No Content</h2>
<a name="Code-Comparison-Only,-Missing-Standard-Block" />
<h2>Code Comparison Only, Missing Standard Block</h2>
<table class="code-comparison">
Expand Down
Loading

0 comments on commit cc82dcd

Please sign in to comment.