[DOC-CVS] [phd] master: Add linking support for enumidentifier elements (#234)

Author: Louis-Arnaud (lacatoire)
Committer: GitHub (web-flow)
Pusher: Girgias
Date: 2026-02-03T18:24:21Z

Commit: https://github.com/php/phd/commit/c9154020cdcf53595eed023618130bc273e34245
Raw diff: https://github.com/php/phd/commit/c9154020cdcf53595eed023618130bc273e34245.diff

Add linking support for enumidentifier elements (#234)

When <enumidentifier> contains a fully qualified name with :: separator
(e.g., RoundingMode::HalfAwayFromZero), the enum name is extracted and
used to generate a link to the corresponding enum documentation page.

Links are not generated in enumsynopsis context (where enumidentifier
defines the case) or when the enum is not found in the index.

Refs php/phd#180

Changed paths:
  A  tests/package/php/data/enumidentifier_link_rendering.xml
  A  tests/package/php/enumidentifier_link_rendering.phpt
  M  phpdotnet/phd/Package/PHP/XHTML.php


Diff:

diff --git a/phpdotnet/phd/Package/PHP/XHTML.php b/phpdotnet/phd/Package/PHP/XHTML.php
index c185336a..6d8a4bec 100644
--- a/phpdotnet/phd/Package/PHP/XHTML.php
+++ b/phpdotnet/phd/Package/PHP/XHTML.php
@@ -125,6 +125,10 @@ abstract class Package_PHP_XHTML extends Package_Generic_XHTML {
                 'classsynopsis' => 'format_classsynopsis_oo_name_text',
             ]
         ],
+        'enumidentifier' => [
+            /* DEFAULT */ 'format_enumidentifier_text',
+            'enumsynopsis' => false,
+        ],
         'methodname'            => array(
             /* DEFAULT */          'format_function_text',
             'constructorsynopsis' => array(
@@ -898,6 +902,25 @@ public function format_classname_text($value, $tag) {
         return '<strong class="' .$tag. '">' .$value. '</strong>';
     }
 
+    public function format_enumidentifier_text($value, $tag) {
+        if (!str_contains($value, '::')) {
+            return $value;
+        }
+
+        list($enumName) = explode('::', $value);
+        $t = strtr($this->normalizeFQN($enumName), ["_" => "-", "\\" => "-"]);
+        $href = Format::getFilename("enum.$t");
+
+        if ($href === false) {
+            return $value;
+        }
+
+        if ($this->chunked) {
+            return '<a href="' . $href . $this->ext . '" class="' . $tag . '">' . $value . '</a>';
+        }
+        return '<a href="#' . $href . '" class="' . $tag . '">' . $value . '</a>';
+    }
+
 
     /*Chunk Functions*/
     private function isChunkedByAttributes(array $attributes): bool {
diff --git a/tests/package/php/data/enumidentifier_link_rendering.xml b/tests/package/php/data/enumidentifier_link_rendering.xml
new file mode 100644
index 00000000..c628be9a
--- /dev/null
+++ b/tests/package/php/data/enumidentifier_link_rendering.xml
@@ -0,0 +1,34 @@
+<?xml version="1.0" encoding="utf-8"?>
+<chapter xml:id="enumidentifier_link_rendering" xmlns="http://docbook.org/ns/docbook">
+
+ <section>
+  <para>1. Enum case inside enumsynopsis (no link - definition context)</para>
+  <enumsynopsis>
+   <enumname>TestEnum</enumname>
+   <enumitem>
+    <enumidentifier>CaseDefinition</enumidentifier>
+   </enumitem>
+  </enumsynopsis>
+ </section>
+
+ <section>
+  <para>2. Enum case reference with FQN (linked)</para>
+  <enumidentifier>Enum\Namespace\Existing_Enum::SomeCase</enumidentifier>
+ </section>
+
+ <section>
+  <para>3. Enum case reference with FQN and leading backslash (linked)</para>
+  <enumidentifier>\Enum\Namespace\Existing_Enum::AnotherCase</enumidentifier>
+ </section>
+
+ <section>
+  <para>4. Enum case without namespace separator (no link)</para>
+  <enumidentifier>JustCaseName</enumidentifier>
+ </section>
+
+ <section>
+  <para>5. Enum case for non-existent enum (no link)</para>
+  <enumidentifier>NonExistent\Enum::SomeCase</enumidentifier>
+ </section>
+
+</chapter>
diff --git a/tests/package/php/enumidentifier_link_rendering.phpt b/tests/package/php/enumidentifier_link_rendering.phpt
new file mode 100644
index 00000000..96268f84
--- /dev/null
+++ b/tests/package/php/enumidentifier_link_rendering.phpt
@@ -0,0 +1,64 @@
+--TEST--
+Enum case (enumidentifier) link rendering
+--FILE--
+<?php
+namespace phpdotnet\phd;
+
+require_once __DIR__ . "/../../setup.php";
+
+$config->xmlFile = __DIR__ . "/data/enumidentifier_link_rendering.xml";
+
+$format = new TestPHPChunkedXHTML($config, $outputHandler);
+$format->SQLiteIndex(
+    null, // $context,
+    null, // $index,
+    "enum.enum-namespace-existing-enum", // $id,
+    "enum.enum-namespace-existing-enum", // $filename,
+    "", // $parent,
+    "", // $sdesc,
+    "", // $ldesc,
+    "phpdoc:classref", // $element,
+    "", // $previous,
+    "", // $next,
+    0, // $chunk
+);
+
+$render = new TestRender(new Reader($outputHandler), $config, $format);
+$render->run();
+?>
+--EXPECT--
+Filename: enumidentifier_link_rendering.html
+Content:
+<div id="enumidentifier_link_rendering" class="chapter">
+
+ <div class="section">
+  <p class="para">1. Enum case inside enumsynopsis (no link - definition context)</p>
+  <div class="classsynopsis"><div class="classsynopsisinfo">
+   <span class="modifier">enum</span> <strong class="classname"><strong class="enumname">TestEnum</strong></strong><br/>{</div>
+   <div class="fieldsynopsis">
+        <span class="modifier">case</span>  <span class="classname">CaseDefinition</span>
+   </div>
+  }</div>
+ </div>
+
+ <div class="section">
+  <p class="para">2. Enum case reference with FQN (linked)</p>
+      <span class="modifier">case</span>  <span class="classname"><a href="enum.enum-namespace-existing-enum.html" class="enumidentifier">Enum\Namespace\Existing_Enum::SomeCase</a></span>
+ </div>
+
+ <div class="section">
+  <p class="para">3. Enum case reference with FQN and leading backslash (linked)</p>
+      <span class="modifier">case</span>  <span class="classname"><a href="enum.enum-namespace-existing-enum.html" class="enumidentifier">\Enum\Namespace\Existing_Enum::AnotherCase</a></span>
+ </div>
+
+ <div class="section">
+  <p class="para">4. Enum case without namespace separator (no link)</p>
+      <span class="modifier">case</span>  <span class="classname">JustCaseName</span>
+ </div>
+
+ <div class="section">
+  <p class="para">5. Enum case for non-existent enum (no link)</p>
+      <span class="modifier">case</span>  <span class="classname">NonExistent\Enum::SomeCase</span>
+ </div>
+
+</div>