From a72d2b5b70faeaf660e76325fdc960194f16a63e Mon Sep 17 00:00:00 2001 From: jrfnl Date: Sat, 7 Dec 2024 14:07:44 +0100 Subject: [PATCH] Generators: show deprecation notice for deprecated methods These methods were _soft_ deprecated in PHPCS 3.12.0 via PR 755 and will be removed in PHPCS 4.0.0. This commit hard deprecates these in case extenders missed the changelog entry. Includes perfunctory tests for the principle of the deprecation notices. --- src/Generators/HTML.php | 25 ++++++++ src/Generators/Markdown.php | 20 +++++++ src/Generators/Text.php | 15 +++++ tests/Core/Generators/Fixtures/HTMLDouble.php | 30 ++++++++++ .../Generators/Fixtures/MarkdownDouble.php | 30 ++++++++++ tests/Core/Generators/HTMLTest.php | 60 +++++++++++++++++++ tests/Core/Generators/MarkdownTest.php | 59 ++++++++++++++++++ 7 files changed, 239 insertions(+) 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