From b10bfa687919fdbaf1444bb6f114bab5d15386cc Mon Sep 17 00:00:00 2001
From: Brent Shaffer <betterbrent@google.com>
Date: Wed, 12 Nov 2025 09:15:02 -0800
Subject: [PATCH 1/2] fix(docs): proto references for php reserved words

---
 dev/src/DocFx/Node/XrefTrait.php  | 10 ++++++++++
 dev/src/DocFx/ReservedNames.php   | 31 +++++++++++++++++++++++++++++++
 dev/tests/Unit/DocFx/NodeTest.php | 13 +++++++++++++
 3 files changed, 54 insertions(+)
 create mode 100644 dev/src/DocFx/ReservedNames.php

diff --git a/dev/src/DocFx/Node/XrefTrait.php b/dev/src/DocFx/Node/XrefTrait.php
index 924eabb7dd33..7bfe0d90570d 100644
--- a/dev/src/DocFx/Node/XrefTrait.php
+++ b/dev/src/DocFx/Node/XrefTrait.php
@@ -17,6 +17,8 @@
 
 namespace Google\Cloud\Dev\DocFx\Node;
 
+use Google\Cloud\Dev\DocFx\ReservedNames;
+
 /**
  * @internal
  */
@@ -115,6 +117,14 @@ function ($matches) {
 
                 $classParts = empty($class) ? [] : explode('.', $class);
 
+                // check for reserved names
+                $classParts = array_map(
+                    fn ($name) => (false === array_search(
+                        strtolower($name), ReservedNames::RESERVED_NAMES
+                    ) ? '' : 'PB') . $name,
+                    $classParts
+                );
+
                 if ($property) {
                     // Convert the underscore property name to camel case getter method name
                     $property = ltrim($property, '.');
diff --git a/dev/src/DocFx/ReservedNames.php b/dev/src/DocFx/ReservedNames.php
new file mode 100644
index 000000000000..fa3e429b381e
--- /dev/null
+++ b/dev/src/DocFx/ReservedNames.php
@@ -0,0 +1,31 @@
+<?php
+
+namespace Google\Cloud\Dev\DocFx;
+
+class ReservedNames
+{
+    /**
+     * Copied from protocolbuffers `src/google/protobuf/compiler/php/names.cc`.
+     * Keep this list up-to-date if modified for future PHP versions
+     *
+     * @see https://github.com/protocolbuffers/protobuf/blob/00a9043d0d79b65b47a048a20d01b16618c8396a/src/google/protobuf/compiler/php/names.cc#L18-L34
+     */
+    public const RESERVED_NAMES = [
+        'abstract',     'and',        'array',        'as',         'break',
+        'callable',     'case',       'catch',        'class',      'clone',
+        'const',        'continue',   'declare',      'default',    'die',
+        'do',           'echo',       'else',         'elseif',     'empty',
+        'enddeclare',   'endfor',     'endforeach',   'endif',      'endswitch',
+        'endwhile',     'eval',       'exit',         'extends',    'final',
+        'finally',      'fn',         'for',          'foreach',    'function',
+        'global',       'goto',       'if',           'implements', 'include',
+        'include_once', 'instanceof', 'insteadof',    'interface',  'isset',
+        'list',         'match',      'namespace',    'new',        'or',
+        'parent',       'print',      'private',      'protected',  'public',
+        'readonly',     'require',    'require_once', 'return',     'self',
+        'static',       'switch',     'throw',        'trait',      'try',
+        'unset',        'use',        'var',          'while',      'xor',
+        'yield',        'int',        'float',        'bool',       'string',
+        'true',         'false',      'null',         'void',       'iterable',
+    ];
+}
\ No newline at end of file
diff --git a/dev/tests/Unit/DocFx/NodeTest.php b/dev/tests/Unit/DocFx/NodeTest.php
index 300c9d0fc9f7..1057014e10e0 100644
--- a/dev/tests/Unit/DocFx/NodeTest.php
+++ b/dev/tests/Unit/DocFx/NodeTest.php
@@ -184,7 +184,9 @@ public function testReplaceProtoRefWithXref(string $description, string $expecte
             private $protoPackages = [
                 'google.cloud.aiplatform.v1' => 'Google\\Cloud\\AIPlatform\\V1',
                 'google.bigtable.admin.v2' => 'Google\\Cloud\\Bigtable\\Admin\\V2',
+                'google.bigtable.v2' => 'Google\\Cloud\\Bigtable\\V2',
                 'google.logging.v2' => 'Google\\Cloud\\Logging\\V2',
+                'google.cloud.servicedirectory.v1' => 'Google\\Cloud\\ServiceDirectory\\V1',
             ];
             public function replace(string $description) {
                 return $this->replaceProtoRef($description);
@@ -273,6 +275,17 @@ public function provideReplaceProtoRefWithXref()
                 . ' <xref uid="\Google\Cloud\AIPlatform\V1\PredictSchemata::getInstanceSchemaUri()">instance_schema_uri</xref>.'
             ],
             [
+                // Reserved word used in class name
+                '[Namespace][google.cloud.servicedirectory.v1.Namespace]',
+                '<xref uid="\Google\Cloud\ServiceDirectory\V1\PBNamespace">Namespace</xref>',
+            ],
+            [
+                // Reserved word used in path name
+                '[Encoding][google.bigtable.v2.Type.String.Encoding]',
+                '<xref uid="\Google\Cloud\Bigtable\V2\Type\PBString\Encoding">Encoding</xref>',
+            ],
+            [
+                // Parenthesis in code samples should not be modified
                 'Testing that a code sample like $foo["bar"]["baz"] does not get replaced',
                 'Testing that a code sample like $foo["bar"]["baz"] does not get replaced'
             ],

From 87b8bae7d11057242a036d7822b4203930486a25 Mon Sep 17 00:00:00 2001
From: Brent Shaffer <betterbrent@google.com>
Date: Fri, 14 Nov 2025 13:06:28 -0800
Subject: [PATCH 2/2] Update dev/src/DocFx/ReservedNames.php

---
 dev/src/DocFx/ReservedNames.php | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/dev/src/DocFx/ReservedNames.php b/dev/src/DocFx/ReservedNames.php
index fa3e429b381e..dd246dfe518d 100644
--- a/dev/src/DocFx/ReservedNames.php
+++ b/dev/src/DocFx/ReservedNames.php
@@ -28,4 +28,4 @@ class ReservedNames
         'yield',        'int',        'float',        'bool',       'string',
         'true',         'false',      'null',         'void',       'iterable',
     ];
-}
\ No newline at end of file
+}