PHPCSStandards · jrfnl · Feb 15, 2025 · Nov 6, 2024
diff --git a/src/Generators/Generator.php b/src/Generators/Generator.php
@@ -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()
 

diff --git a/tests/Core/Generators/Expectations/ExpectedOutputDocumentationTitlePCREFallback.html b/tests/Core/Generators/Expectations/ExpectedOutputDocumentationTitlePCREFallback.html
@@ -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>
diff --git a/tests/Core/Generators/Expectations/ExpectedOutputDocumentationTitlePCREFallback.md b/tests/Core/Generators/Expectations/ExpectedOutputDocumentationTitlePCREFallback.md
@@ -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)
diff --git a/tests/Core/Generators/Expectations/ExpectedOutputDocumentationTitlePCREFallback.txt b/tests/Core/Generators/Expectations/ExpectedOutputDocumentationTitlePCREFallback.txt
@@ -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.
+
diff --git a/tests/Core/Generators/Expectations/ExpectedOutputInvalidDocumentationTitleEmpty.html b/tests/Core/Generators/Expectations/ExpectedOutputInvalidDocumentationTitleEmpty.html
@@ -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>

diff --git a/tests/Core/Generators/Expectations/ExpectedOutputInvalidDocumentationTitleEmpty.md b/tests/Core/Generators/Expectations/ExpectedOutputInvalidDocumentationTitleEmpty.md
@@ -1,6 +1,6 @@
 # GeneratorTest Coding Standard
 
-## 
+## Documentation Title Empty
 
 The above &quot;documentation&quot; element has an empty title attribute.
   <table>

diff --git a/tests/Core/Generators/Expectations/ExpectedOutputInvalidDocumentationTitleEmpty.txt b/tests/Core/Generators/Expectations/ExpectedOutputInvalidDocumentationTitleEmpty.txt
@@ -1,7 +1,7 @@
 
------------------------------------
-| GENERATORTEST CODING STANDARD:  |
------------------------------------
+------------------------------------------------------------
+| GENERATORTEST CODING STANDARD: DOCUMENTATION TITLE EMPTY |
+------------------------------------------------------------
 
 The above "documentation" element has an empty title attribute.
 

diff --git a/tests/Core/Generators/Expectations/ExpectedOutputInvalidDocumentationTitleMissing.html b/tests/Core/Generators/Expectations/ExpectedOutputInvalidDocumentationTitleMissing.html
@@ -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>

diff --git a/.../Core/Generators/Expectations/ExpectedOutputInvalidDocumentationTitleMissing.md b/.../Core/Generators/Expectations/ExpectedOutputInvalidDocumentationTitleMissing.md
@@ -1,6 +1,6 @@
 # GeneratorTest Coding Standard
 
-## 
+## Documentation Title Missing
 
 The above &quot;documentation&quot; element is missing the title attribute.
   <table>

diff --git a/tests/Core/Generators/Expectations/ExpectedOutputInvalidDocumentationTitleMissing.txt b/tests/Core/Generators/Expectations/ExpectedOutputInvalidDocumentationTitleMissing.txt
@@ -1,7 +1,7 @@
 
------------------------------------
-| GENERATORTEST CODING STANDARD:  |
------------------------------------
+--------------------------------------------------------------
+| GENERATORTEST CODING STANDARD: DOCUMENTATION TITLE MISSING |
+--------------------------------------------------------------
 
 The above "documentation" element is missing the title attribute.
 

diff --git a/...erators/Fixtures/StandardWithDocs/Docs/Content/DocumentationTitlePCREFallbackStandard.xml b/...erators/Fixtures/StandardWithDocs/Docs/Content/DocumentationTitlePCREFallbackStandard.xml
@@ -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>
diff --git a/...nerators/Fixtures/StandardWithDocs/Sniffs/Content/DocumentationTitlePCREFallbackSniff.php b/...nerators/Fixtures/StandardWithDocs/Sniffs/Content/DocumentationTitlePCREFallbackSniff.php
@@ -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 {}
diff --git a/tests/Core/Generators/GeneratorTest.php b/tests/Core/Generators/GeneratorTest.php
@@ -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.
      *

diff --git a/tests/Core/Generators/HTMLTest.php b/tests/Core/Generators/HTMLTest.php
@@ -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',

diff --git a/tests/Core/Generators/MarkdownTest.php b/tests/Core/Generators/MarkdownTest.php
@@ -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',

diff --git a/tests/Core/Generators/TextTest.php b/tests/Core/Generators/TextTest.php
@@ -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',