Handle Deprecated attribute for global constants

scripts/parse-stub.php

@@ -80,6 +80,7 @@ function file_to_doc_constants(string $path)
     count($status->missing), ' missing constants', PHP_EOL,
     count($status->incorrectTypes), ' constants with incorrect types documented', PHP_EOL,
     count($status->incorrectIdForLinking), ' documented constants with incorrect IDs for linking', PHP_EOL,
+    count($status->deprecatedInStub), ' deprecated constants (in stubs)', PHP_EOL,
     $status->valid, ' valid constants', PHP_EOL;
 echo "Total doc constants parsed = $totalDocConst\n";
 echo "Total stub constants parsed = ", count($constants), "\n";

src/Differ/ConstantListDiff.php

@@ -7,11 +7,15 @@
 
 final readonly class ConstantListDiff
 {
-    /** @param array<string, array{0: ConstantMetaData, 1: string}> $incorrectTypes */
+    /**
+     * @param array<string, array{0: ConstantMetaData, 1: string}> $incorrectTypes
+     * @param list<ConstantMetaData> $deprecatedInStub
+     */
     public function __construct(
         readonly int $valid,
         readonly array $incorrectTypes,
         readonly ConstantList $missing,
         readonly ConstantList $incorrectIdForLinking,
+        readonly array $deprecatedInStub = [],
     ) {}
 }

src/Differ/ConstantListDiffer.php

@@ -13,6 +13,7 @@ public static function diff(ConstantList $fromStubs, ConstantList $fromDocs): Co
         $missingDocs = [];
         $incorrectTypes = [];
         $incorrectIdForLinking = [];
+        $deprecatedInStub = [];
 
         foreach ($fromStubs->constants as $name => $constant) {
             if (!array_key_exists($name, $docConstants)) {
@@ -30,13 +31,17 @@ public static function diff(ConstantList $fromStubs, ConstantList $fromDocs): Co
             if ($constant->id !== $docConstants[$name]->id) {
                 $incorrectIdForLinking[$name] = $docConstants[$name];
             }
+            if ($constant->isDeprecated) {
+                $deprecatedInStub[] = $constant;
+            }
         }
 
         return new ConstantListDiff(
             $totalStubConstants - count($incorrectTypes) - count($missingDocs) - count($incorrectIdForLinking),
             $incorrectTypes,
             new ConstantList($missingDocs),
             new ConstantList($incorrectIdForLinking),
+            $deprecatedInStub,
         );
     }
 }

src/Reports/ConstantDocumentationReport.php

@@ -32,6 +32,7 @@ public static function generateHtmlReport(ConstantListDiff $differ, string $file
         self::generateHtmlReportMissingConstants($fp, $differ->missing);
         self::generateHtmlReportIncorrectDocumentedConstantIdsForLinking($fp, $differ->incorrectIdForLinking);
         self::generateHtmlReportIncorrectConstantTypes($fp, $differ->incorrectTypes);
+        self::generateHtmlReportDeprecatedConstants($fp, $differ->deprecatedInStub);
 
         fputs($fp, <<<'HTML_END'
 </body>
@@ -180,4 +181,41 @@ private static function generateHtmlReportIncorrectDocumentedConstantIdsForLinki
             fputs($fp, '<p>No Documented Constants with Incorrect XML IDs for linking</p>');
         }
     }
+
+    /**
+     * @param resource $fp
+     * @param list<ConstantMetaData> $deprecatedConstants
+     */
+    private static function generateHtmlReportDeprecatedConstants($fp, array $deprecatedConstants): void
+    {
+        if (count($deprecatedConstants) > 0) {
+            fputs($fp, <<<'HTML_DEPRECATED'
+<section>
+ <h2>Deprecated Constants</h2>
+HTML_DEPRECATED);
+            fputs($fp, '<p>Constants marked as deprecated in stubs: ' . count($deprecatedConstants) . '</p>');
+            fputs($fp, <<<'HTML_DEPRECATED_TABLE_START'
+ <table>
+  <thead>
+    <tr>
+      <th scope="col">Name</th>
+      <th scope="col">Type</th>
+      <th scope="col">Value</th>
+      <th scope="col">Extension</th>
+    </tr>
+  </thead>
+  <tbody>
+HTML_DEPRECATED_TABLE_START);
+            foreach ($deprecatedConstants as $constant) {
+                fputs($fp, self::generateHtmlReportRow($constant));
+            }
+            fputs($fp, <<<'HTML_DEPRECATED_TABLE_END'
+  </tbody>
+ </table>
+</section>
+HTML_DEPRECATED_TABLE_END);
+        } else {
+            fputs($fp, '<p>No deprecated constants</p>');
+        }
+    }
 }