Skip to content

Generators: show deprecation notice for deprecated methods #889

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Apr 14, 2025
+239 −0
Merged

Generators: show deprecation notice for deprecated methods #889

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 25 additions & 0 deletions src/Generators/HTML.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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()
Expand Down Expand Up @@ -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()
Expand Down Expand Up @@ -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()
Expand Down Expand Up @@ -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()
Expand Down Expand Up @@ -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()
Expand Down
20 changes: 20 additions & 0 deletions src/Generators/Markdown.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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()
Expand Down Expand Up @@ -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()
Expand Down Expand Up @@ -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()
Expand Down Expand Up @@ -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()
Expand Down
15 changes: 15 additions & 0 deletions src/Generators/Text.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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()
Expand Down Expand Up @@ -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()
Expand Down Expand Up @@ -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()
Expand Down
30 changes: 30 additions & 0 deletions tests/Core/Generators/Fixtures/HTMLDouble.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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();
}
}
30 changes: 30 additions & 0 deletions tests/Core/Generators/Fixtures/MarkdownDouble.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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();
}
}
60 changes: 60 additions & 0 deletions tests/Core/Generators/HTMLTest.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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<string, array<string, string>>
*/
public static function dataCallingDeprecatedMethodThrowsDeprecationNotice()
{
return [
'printHeader()' => ['printHeader'],
'printToc()' => ['printToc'],
'printFooter()' => ['printFooter'],
];

}//end dataCallingDeprecatedMethodThrowsDeprecationNotice()


}//end class
59 changes: 59 additions & 0 deletions tests/Core/Generators/MarkdownTest.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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<string, array<string, string>>
*/
public static function dataCallingDeprecatedMethodThrowsDeprecationNotice()
{
return [
'printHeader()' => ['printHeader'],
'printFooter()' => ['printFooter'],
];

}//end dataCallingDeprecatedMethodThrowsDeprecationNotice()


}//end class