Skip to content

Generator::getTitle(): fall back to file name if title is missing #820

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.

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
Feb 15, 2025
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
17 changes: 16 additions & 1 deletion src/Generators/Generator.php
Original file line number Diff line number Diff line change
Expand Up @@ -83,7 +83,22 @@ public function __construct(Ruleset $ruleset)
*/
protected function getTitle(DOMNode $doc)
{
return $doc->getAttribute('title');
$title = $doc->getAttribute('title');

if (empty($title) === true) {
// Fall back to the sniff name if no title was supplied.
$fileName = $doc->ownerDocument->documentURI;
$lastSlash = strrpos($fileName, '/');
if (is_int($lastSlash) === true) {
// Get the sniff name without "Standard.xml".
$title = substr($fileName, ($lastSlash + 1), -12);

// Split the sniff name to individual words.
$title = preg_replace('`[-._]|(?<=[a-z])(?=[A-Z])|(?<=[A-Z])(?=[A-Z][a-z])`', '$1 $2', $title);
}
}

return $title;

}//end getTitle()

Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,79 @@
<html>
<head>
<title>GeneratorTest Coding Standards</title>
<style>
body {
background-color: #FFFFFF;
font-size: 14px;
font-family: Arial, Helvetica, sans-serif;
color: #000000;
}

h1 {
color: #666666;
font-size: 20px;
font-weight: bold;
margin-top: 0px;
background-color: #E6E7E8;
padding: 20px;
border: 1px solid #BBBBBB;
}

h2 {
color: #00A5E3;
font-size: 16px;
font-weight: normal;
margin-top: 50px;
}

.code-comparison {
width: 100%;
}

.code-comparison td {
border: 1px solid #CCCCCC;
}

.code-comparison-title, .code-comparison-code {
font-family: Arial, Helvetica, sans-serif;
font-size: 12px;
color: #000000;
vertical-align: top;
padding: 4px;
width: 50%;
background-color: #F1F1F1;
line-height: 15px;
}

.code-comparison-code {
font-family: Courier;
background-color: #F9F9F9;
}

.code-comparison-highlight {
background-color: #DDF1F7;
border: 1px solid #00A5E3;
line-height: 15px;
}

.tag-line {
text-align: center;
width: 100%;
margin-top: 30px;
font-size: 12px;
}

.tag-line a {
color: #000000;
}
</style>
</head>
<body>
<h1>GeneratorTest Coding Standards</h1>
<a name="Documentation-Title-PCRE-Fallback" />
<h2>Documentation Title PCRE Fallback</h2>
<p class="text">Testing the document title can get determined from the sniff name if missing.</p>
<p class="text">This file name contains an acronym on purpose to test the word splitting.</p>
<div class="tag-line">Documentation generated on #REDACTED# by <a href="https://github.com/PHPCSStandards/PHP_CodeSniffer">PHP_CodeSniffer #VERSION#</a></div>
</body>
</html>
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
# GeneratorTest Coding Standard

## Documentation Title PCRE Fallback

Testing the document title can get determined from the sniff name if missing.

This file name contains an acronym on purpose to test the word splitting.

Documentation generated on *REDACTED* by [PHP_CodeSniffer *VERSION*](https://github.com/PHPCSStandards/PHP_CodeSniffer)
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@

--------------------------------------------------------------------
| GENERATORTEST CODING STANDARD: DOCUMENTATION TITLE PCRE FALLBACK |
--------------------------------------------------------------------

Testing the document title can get determined from the sniff name if missing.

This file name contains an acronym on purpose to test the word splitting.

Original file line number Diff line number Diff line change
Expand Up @@ -70,8 +70,8 @@
</head>
<body>
<h1>GeneratorTest Coding Standards</h1>
<a name="" />
<h2></h2>
<a name="Documentation-Title-Empty" />
<h2>Documentation Title Empty</h2>
<p class="text">The above &quot;documentation&quot; element has an empty title attribute.</p>
<table class="code-comparison">
<tr>
Expand Down
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# GeneratorTest Coding Standard

##
## Documentation Title Empty

The above &quot;documentation&quot; element has an empty title attribute.
<table>
Expand Down
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@

-----------------------------------
| GENERATORTEST CODING STANDARD: |
-----------------------------------
------------------------------------------------------------
| GENERATORTEST CODING STANDARD: DOCUMENTATION TITLE EMPTY |
------------------------------------------------------------

The above "documentation" element has an empty title attribute.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -70,8 +70,8 @@
</head>
<body>
<h1>GeneratorTest Coding Standards</h1>
<a name="" />
<h2></h2>
<a name="Documentation-Title-Missing" />
<h2>Documentation Title Missing</h2>
<p class="text">The above &quot;documentation&quot; element is missing the title attribute.</p>
<table class="code-comparison">
<tr>
Expand Down
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# GeneratorTest Coding Standard

##
## Documentation Title Missing

The above &quot;documentation&quot; element is missing the title attribute.
<table>
Expand Down
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@

-----------------------------------
| GENERATORTEST CODING STANDARD: |
-----------------------------------
--------------------------------------------------------------
| GENERATORTEST CODING STANDARD: DOCUMENTATION TITLE MISSING |
--------------------------------------------------------------

The above "documentation" element is missing the title attribute.

Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
<documentation>
<standard>
<![CDATA[
Testing the document title can get determined from the sniff name if missing.
This file name contains an acronym on purpose to test the word splitting.
]]>
</standard>
</documentation>
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
<?php
/**
* Test fixture.
*
* @see \PHP_CodeSniffer\Tests\Core\Generators\GeneratorTest
*/

namespace Fixtures\StandardWithDocs\Sniffs\Content;

use Fixtures\StandardWithDocs\Sniffs\DummySniff;

final class DocumentationTitlePCREFallbackSniff extends DummySniff {}
33 changes: 33 additions & 0 deletions tests/Core/Generators/GeneratorTest.php
Original file line number Diff line number Diff line change
Expand Up @@ -192,6 +192,39 @@ public static function dataGeneratingDocs()
}//end dataGeneratingDocs()


/**
* Verify that if the `<documentation>` title is missing, it will fallback to the file name
* and split the CamelCaps name correctly.
*
* @return void
*/
public function testGetTitleFallbackToFilename()
{
// Set up the ruleset.
$standard = __DIR__.'/AllValidDocsTest.xml';
$sniffs = 'StandardWithDocs.Content.DocumentationTitlePCREFallback';
$config = new ConfigDouble(["--standard=$standard", "--sniffs=$sniffs"]);
$ruleset = new Ruleset($config);

// In tests, the `--sniffs` setting doesn't work out of the box.
$sniffParts = explode('.', $sniffs);
$sniffFile = __DIR__.DIRECTORY_SEPARATOR.'Fixtures'.DIRECTORY_SEPARATOR.$sniffParts[0].DIRECTORY_SEPARATOR;
$sniffFile .= 'Sniffs'.DIRECTORY_SEPARATOR.$sniffParts[1].DIRECTORY_SEPARATOR.$sniffParts[2].'Sniff.php';

$sniffParts = array_map('strtolower', $sniffParts);
$sniffName = $sniffParts[0].'\sniffs\\'.$sniffParts[1].'\\'.$sniffParts[2].'sniff';
$restrictions = [$sniffName => true];
$ruleset->registerSniffs([$sniffFile], $restrictions, []);

// Make the test OS independent.
$this->expectOutputString('Documentation Title PCRE Fallback'.PHP_EOL);

$generator = new MockGenerator($ruleset);
$generator->generate();

}//end testGetTitleFallbackToFilename()


/**
* Test that the documentation for each standard passed on the command-line is shown separately.
*
Expand Down
4 changes: 4 additions & 0 deletions tests/Core/Generators/HTMLTest.php
Original file line number Diff line number Diff line change
Expand Up @@ -133,6 +133,10 @@ public static function dataDocSpecifics()
'sniffs' => 'StandardWithDocs.Content.DocumentationTitleLength',
'pathToExpected' => __DIR__.'/Expectations/ExpectedOutputDocumentationTitleLength.html',
],
'Documentation title: fallback to file name' => [
'sniffs' => 'StandardWithDocs.Content.DocumentationTitlePCREFallback',
'pathToExpected' => __DIR__.'/Expectations/ExpectedOutputDocumentationTitlePCREFallback.html',
],
'Standard Element: blank line handling' => [
'sniffs' => 'StandardWithDocs.Content.StandardBlankLines',
'pathToExpected' => __DIR__.'/Expectations/ExpectedOutputStandardBlankLines.html',
Expand Down
4 changes: 4 additions & 0 deletions tests/Core/Generators/MarkdownTest.php
Original file line number Diff line number Diff line change
Expand Up @@ -133,6 +133,10 @@ public static function dataDocSpecifics()
'sniffs' => 'StandardWithDocs.Content.DocumentationTitleLength',
'pathToExpected' => __DIR__.'/Expectations/ExpectedOutputDocumentationTitleLength.md',
],
'Documentation title: fallback to file name' => [
'sniffs' => 'StandardWithDocs.Content.DocumentationTitlePCREFallback',
'pathToExpected' => __DIR__.'/Expectations/ExpectedOutputDocumentationTitlePCREFallback.md',
],
'Standard Element: blank line handling' => [
'sniffs' => 'StandardWithDocs.Content.StandardBlankLines',
'pathToExpected' => __DIR__.'/Expectations/ExpectedOutputStandardBlankLines.md',
Expand Down
4 changes: 4 additions & 0 deletions tests/Core/Generators/TextTest.php
Original file line number Diff line number Diff line change
Expand Up @@ -133,6 +133,10 @@ public static function dataDocSpecifics()
'sniffs' => 'StandardWithDocs.Content.DocumentationTitleLength',
'pathToExpected' => __DIR__.'/Expectations/ExpectedOutputDocumentationTitleLength.txt',
],
'Documentation title: fallback to file name' => [
'sniffs' => 'StandardWithDocs.Content.DocumentationTitlePCREFallback',
'pathToExpected' => __DIR__.'/Expectations/ExpectedOutputDocumentationTitlePCREFallback.txt',
],
'Standard Element: blank line handling' => [
'sniffs' => 'StandardWithDocs.Content.StandardBlankLines',
'pathToExpected' => __DIR__.'/Expectations/ExpectedOutputStandardBlankLines.txt',
Expand Down
Loading