diff --git a/src/Generators/HTML.php b/src/Generators/HTML.php index 4e63e4fc0a..7a8408f17a 100644 --- a/src/Generators/HTML.php +++ b/src/Generators/HTML.php @@ -164,6 +164,11 @@ public function generate() */ protected function printHeader() { + trigger_error( + 'The '.__METHOD__.'() method is deprecated. Use "echo '.__CLASS__.'::getFormattedHeader()" instead.', + E_USER_DEPRECATED + ); + echo $this->getFormattedHeader(); }//end printHeader() @@ -208,6 +213,11 @@ protected function getFormattedHeader() */ protected function printToc() { + trigger_error( + 'The '.__METHOD__.'() method is deprecated. Use "echo '.__CLASS__.'::getFormattedToc()" instead.', + E_USER_DEPRECATED + ); + echo $this->getFormattedToc(); }//end printToc() @@ -260,6 +270,11 @@ protected function getFormattedToc() */ protected function printFooter() { + trigger_error( + 'The '.__METHOD__.'() method is deprecated. Use "echo '.__CLASS__.'::getFormattedFooter()" instead.', + E_USER_DEPRECATED + ); + echo $this->getFormattedFooter(); }//end printFooter() @@ -367,6 +382,11 @@ private function titleToAnchor($title) */ protected function printTextBlock(DOMNode $node) { + trigger_error( + 'The '.__METHOD__.'() method is deprecated. Use "echo '.__CLASS__.'::getFormattedTextBlock()" instead.', + E_USER_DEPRECATED + ); + echo $this->getFormattedTextBlock($node); }//end printTextBlock() @@ -437,6 +457,11 @@ protected function getFormattedTextBlock(DOMNode $node) */ protected function printCodeComparisonBlock(DOMNode $node) { + trigger_error( + 'The '.__METHOD__.'() method is deprecated. Use "echo '.__CLASS__.'::getFormattedCodeComparisonBlock()" instead.', + E_USER_DEPRECATED + ); + echo $this->getFormattedCodeComparisonBlock($node); }//end printCodeComparisonBlock() diff --git a/src/Generators/Markdown.php b/src/Generators/Markdown.php index 112700e2e6..f73fcd935f 100644 --- a/src/Generators/Markdown.php +++ b/src/Generators/Markdown.php @@ -57,6 +57,11 @@ public function generate() */ protected function printHeader() { + trigger_error( + 'The '.__METHOD__.'() method is deprecated. Use "echo '.__CLASS__.'::getFormattedHeader()" instead.', + E_USER_DEPRECATED + ); + echo $this->getFormattedHeader(); }//end printHeader() @@ -89,6 +94,11 @@ protected function getFormattedHeader() */ protected function printFooter() { + trigger_error( + 'The '.__METHOD__.'() method is deprecated. Use "echo '.__CLASS__.'::getFormattedFooter()" instead.', + E_USER_DEPRECATED + ); + echo $this->getFormattedFooter(); }//end printFooter() @@ -157,6 +167,11 @@ protected function processSniff(DOMNode $doc) */ protected function printTextBlock(DOMNode $node) { + trigger_error( + 'The '.__METHOD__.'() method is deprecated. Use "echo '.__CLASS__.'::getFormattedTextBlock()" instead.', + E_USER_DEPRECATED + ); + echo $this->getFormattedTextBlock($node); }//end printTextBlock() @@ -225,6 +240,11 @@ protected function getFormattedTextBlock(DOMNode $node) */ protected function printCodeComparisonBlock(DOMNode $node) { + trigger_error( + 'The '.__METHOD__.'() method is deprecated. Use "echo '.__CLASS__.'::getFormattedCodeComparisonBlock()" instead.', + E_USER_DEPRECATED + ); + echo $this->getFormattedCodeComparisonBlock($node); }//end printCodeComparisonBlock() diff --git a/src/Generators/Text.php b/src/Generators/Text.php index 4beb45abf1..5dae8c1ab2 100644 --- a/src/Generators/Text.php +++ b/src/Generators/Text.php @@ -62,6 +62,11 @@ public function processSniff(DOMNode $doc) */ protected function printTitle(DOMNode $doc) { + trigger_error( + 'The '.__METHOD__.'() method is deprecated. Use "echo '.__CLASS__.'::getFormattedTitle()" instead.', + E_USER_DEPRECATED + ); + echo $this->getFormattedTitle($doc); }//end printTitle() @@ -109,6 +114,11 @@ protected function getFormattedTitle(DOMNode $doc) */ protected function printTextBlock(DOMNode $node) { + trigger_error( + 'The '.__METHOD__.'() method is deprecated. Use "echo '.__CLASS__.'::getFormattedTextBlock()" instead.', + E_USER_DEPRECATED + ); + echo $this->getFormattedTextBlock($node); }//end printTextBlock() @@ -155,6 +165,11 @@ protected function getFormattedTextBlock(DOMNode $node) */ protected function printCodeComparisonBlock(DOMNode $node) { + trigger_error( + 'The '.__METHOD__.'() method is deprecated. Use "echo '.__CLASS__.'::getFormattedCodeComparisonBlock()" instead.', + E_USER_DEPRECATED + ); + echo $this->getFormattedCodeComparisonBlock($node); }//end printCodeComparisonBlock() diff --git a/tests/Core/Generators/Fixtures/HTMLDouble.php b/tests/Core/Generators/Fixtures/HTMLDouble.php index 8b737fb7c4..695c0c6d2f 100644 --- a/tests/Core/Generators/Fixtures/HTMLDouble.php +++ b/tests/Core/Generators/Fixtures/HTMLDouble.php @@ -37,4 +37,34 @@ public function getRealFooter() { return parent::getFormattedFooter(); } + + /** + * [VISIBILITY WIDENING ONLY] Print the header of the HTML page. + * + * @return void + */ + public function printHeader() + { + parent::printHeader(); + } + + /** + * [VISIBILITY WIDENING ONLY] Print the table of contents for the standard. + * + * @return void + */ + public function printToc() + { + parent::printToc(); + } + + /** + * [VISIBILITY WIDENING ONLY] Print the footer of the HTML page. + * + * @return void + */ + public function printFooter() + { + parent::printFooter(); + } } diff --git a/tests/Core/Generators/Fixtures/MarkdownDouble.php b/tests/Core/Generators/Fixtures/MarkdownDouble.php index e783f7dda7..79dc6b0bf2 100644 --- a/tests/Core/Generators/Fixtures/MarkdownDouble.php +++ b/tests/Core/Generators/Fixtures/MarkdownDouble.php @@ -35,4 +35,34 @@ public function getRealFooter() { return parent::getFormattedFooter(); } + + /** + * [VISIBILITY WIDENING ONLY] Print the header of the HTML page. + * + * @return void + */ + public function printHeader() + { + parent::printHeader(); + } + + /** + * [VISIBILITY WIDENING ONLY] Print the table of contents for the standard. + * + * @return void + */ + public function printToc() + { + parent::printToc(); + } + + /** + * [VISIBILITY WIDENING ONLY] Print the footer of the HTML page. + * + * @return void + */ + public function printFooter() + { + parent::printFooter(); + } } diff --git a/tests/Core/Generators/HTMLTest.php b/tests/Core/Generators/HTMLTest.php index a8ac84a8ab..91cd7d1e55 100644 --- a/tests/Core/Generators/HTMLTest.php +++ b/tests/Core/Generators/HTMLTest.php @@ -363,4 +363,64 @@ public function testFooterDoesntThrowWarningOnMissingTimezone() }//end testFooterDoesntThrowWarningOnMissingTimezone() + /** + * Perfunctory test to verify that extenders which call deprecated methods will see a deprecation notice. + * + * Note: not all deprecated methods are tested as some need arguments. + * + * @param string $methodName Name of the deprecated method to test. + * + * @dataProvider dataCallingDeprecatedMethodThrowsDeprecationNotice + * + * @return void + */ + public function testCallingDeprecatedMethodThrowsDeprecationNotice($methodName) + { + $exceptionClass = 'PHPUnit\Framework\Error\Deprecated'; + if (class_exists($exceptionClass) === false) { + $exceptionClass = 'PHPUnit_Framework_Error_Deprecated'; + } + + $regex = '`^The PHP_CodeSniffer\\\\Generators\\\\HTML::%s\(\) method is deprecated\. Use "echo [^\s]+::%s\(\)" instead\.$`'; + $regex = sprintf($regex, preg_quote($methodName, '`'), str_replace('print', 'getFormatted', $methodName)); + + if (method_exists($this, 'expectExceptionMessageMatches') === true) { + $this->expectException($exceptionClass); + $this->expectExceptionMessageMatches($regex); + } else if (method_exists($this, 'expectExceptionMessageRegExp') === true) { + // PHPUnit < 8.4.0. + $this->expectException($exceptionClass); + $this->expectExceptionMessageRegExp($regex); + } else { + // PHPUnit < 5.2.0. + $this->setExpectedExceptionRegExp($exceptionClass, $regex); + } + + // Set up the ruleset. + $standard = __DIR__.'/OneDocTest.xml'; + $config = new ConfigDouble(["--standard=$standard"]); + $ruleset = new Ruleset($config); + + $generator = new HTMLDouble($ruleset); + $generator->$methodName(); + + }//end testCallingDeprecatedMethodThrowsDeprecationNotice() + + + /** + * Data provider. + * + * @return array> + */ + public static function dataCallingDeprecatedMethodThrowsDeprecationNotice() + { + return [ + 'printHeader()' => ['printHeader'], + 'printToc()' => ['printToc'], + 'printFooter()' => ['printFooter'], + ]; + + }//end dataCallingDeprecatedMethodThrowsDeprecationNotice() + + }//end class diff --git a/tests/Core/Generators/MarkdownTest.php b/tests/Core/Generators/MarkdownTest.php index 6bc2c4fba2..f9fd47796b 100644 --- a/tests/Core/Generators/MarkdownTest.php +++ b/tests/Core/Generators/MarkdownTest.php @@ -335,4 +335,63 @@ public function testFooterDoesntThrowWarningOnMissingTimezone() }//end testFooterDoesntThrowWarningOnMissingTimezone() + /** + * Perfunctory test to verify that extenders which call deprecated methods will see a deprecation notice. + * + * Note: not all deprecated methods are tested as some need arguments. + * + * @param string $methodName Name of the deprecated method to test. + * + * @dataProvider dataCallingDeprecatedMethodThrowsDeprecationNotice + * + * @return void + */ + public function testCallingDeprecatedMethodThrowsDeprecationNotice($methodName) + { + $exceptionClass = 'PHPUnit\Framework\Error\Deprecated'; + if (class_exists($exceptionClass) === false) { + $exceptionClass = 'PHPUnit_Framework_Error_Deprecated'; + } + + $regex = '`^The PHP_CodeSniffer\\\\Generators\\\\Markdown::%s\(\) method is deprecated\. Use "echo [^\s]+::%s\(\)" instead\.$`'; + $regex = sprintf($regex, preg_quote($methodName, '`'), str_replace('print', 'getFormatted', $methodName)); + + if (method_exists($this, 'expectExceptionMessageMatches') === true) { + $this->expectException($exceptionClass); + $this->expectExceptionMessageMatches($regex); + } else if (method_exists($this, 'expectExceptionMessageRegExp') === true) { + // PHPUnit < 8.4.0. + $this->expectException($exceptionClass); + $this->expectExceptionMessageRegExp($regex); + } else { + // PHPUnit < 5.2.0. + $this->setExpectedExceptionRegExp($exceptionClass, $regex); + } + + // Set up the ruleset. + $standard = __DIR__.'/OneDocTest.xml'; + $config = new ConfigDouble(["--standard=$standard"]); + $ruleset = new Ruleset($config); + + $generator = new MarkdownDouble($ruleset); + $generator->$methodName(); + + }//end testCallingDeprecatedMethodThrowsDeprecationNotice() + + + /** + * Data provider. + * + * @return array> + */ + public static function dataCallingDeprecatedMethodThrowsDeprecationNotice() + { + return [ + 'printHeader()' => ['printHeader'], + 'printFooter()' => ['printFooter'], + ]; + + }//end dataCallingDeprecatedMethodThrowsDeprecationNotice() + + }//end class