Fix inherited methods missing through deep stub chains

Author: AJenbo

docs/CHANGELOG.md

@@ -13,6 +13,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Nullable and generic types in class lookup.** Variables typed as `?ClassName` or `Collection<Item>` now resolve correctly across all code paths. Previously the `?` prefix and generic parameters were not stripped before class lookup, causing the type engine to treat them as unknown types. This fixes completion, hover, go-to-definition, and false-positive diagnostics for any variable whose type uses the nullable shorthand or carries generic arguments.
 - **`@see` references with qualified class names.** Docblock `@see Fully\Qualified\ClassName` references no longer have the file's namespace prepended, which previously produced doubled names like `App\Models\App\Models\User`. Qualified names in `@see` tags are now treated as fully-qualified.
 - **Ternary and null-coalesce member access.** Accessing a member on a ternary or null-coalesce expression (e.g. `($a ?: $b)->property`, `($x ?? $y)->method()`) now resolves correctly for hover, go-to-definition, and diagnostics. Previously the subject extraction produced an empty string, causing a confusing "Cannot resolve type of ''" hint and no hover information.
+- **Inherited methods missing through deep stub chains.** Methods like `getCode()` and `getMessage()` are now found on classes that inherit through multi-level chains where intermediate classes live in stubs (e.g. `QueryException` → `PDOException` → `RuntimeException` → `Exception`). Previously the inheritance chain broke when a stub file contained multiple namespace blocks, causing parent class names to be resolved against the wrong namespace.
 - **False-positive diagnostics for same-named variables in different methods.** When two methods in the same class both used a variable like `$order`, the diagnostic cache resolved it once and reused that type for every other method in the class. The second method saw the wrong type and flagged valid member accesses as unknown. Both the per-file subject cache and the cross-collector resolution cache are now scoped to the enclosing function/method/closure body, so each method resolves variables independently.
 - **False-positive diagnostics for `$this` inside traits.** Accessing host-class members via `$this->`, `self::`, `static::`, or `parent::` inside a trait method no longer produces "not found" warnings. Traits are incomplete by nature and expect the host class to provide these members.
 - **Type narrowing inside `return` statements.** `instanceof` checks in `&&` chains and ternary conditions now narrow the variable type when the expression is the operand of a `return` statement. Previously, `return $e instanceof QueryException && $e->errorInfo;` would flag `errorInfo` as unknown because narrowing only applied inside standalone expression statements and `if` conditions.

docs/todo.md

@@ -104,7 +104,6 @@ unlikely to move the needle for most users.
 | B3  | [Trait static/self suppression not applied inside closures](todo/bugs.md#b3-trait-staticself-suppression-not-applied-inside-closures)                         | Medium      | Low         |
 | B4  | [Variable reassignment loses type when parameter name is reused](todo/bugs.md#b4-variable-reassignment-loses-type-when-parameter-name-is-reused)             | Medium      | Medium      |
 | B7  | [Overloaded built-in function signatures in stubs](todo/bugs.md#b7-overloaded-built-in-function-signatures-in-stubs)                                         | Low         | Low         |
-| B8  | [`getCode`/`getMessage` not found through deep inheritance chains](todo/bugs.md#b8-getcodemessage-not-found-through-deep-inheritance-chains)                 | Low         | Low         |
 |     | **[Completion](todo/completion.md)**                                                                                                                         |             |             |
 | C1  | Array functions needing new code paths                                                                                                                       | Medium     | High        |
 | C10 | [Lazy documentation via `completionItem/resolve`](todo/completion.md#c10-lazy-documentation-via-completionitemresolve)                                        | Medium     | Medium      |

docs/todo/bugs.md

@@ -114,25 +114,3 @@ this map before flagging. The map only needs entries for functions
 where the stub's single signature cannot represent the valid call
 forms.
 
----
-
-#### B8. `getCode`/`getMessage` not found through deep inheritance chains
-
-| | |
-|---|---|
-| **Impact** | Low |
-| **Effort** | Low |
-
-Methods inherited from `Throwable` (like `getCode()` and
-`getMessage()`) are not found on `QueryException`, which inherits
-through `QueryException → PDOException → RuntimeException → Exception`.
-The chain involves both vendor classes and stub classes.
-
-**Observed:** 3 diagnostics in `shared` for `getCode()` and
-`getMessage()` on `Illuminate\Database\QueryException`.
-
-**Fix:** Investigate whether the inheritance chain breaks at the
-vendor-to-stub boundary (PDOException is in stubs, RuntimeException
-is in stubs). The chain resolution may stop walking when it crosses
-from a vendor class to a stub class, or the depth limit may be
-insufficient.

src/parser/mod.rs

@@ -969,6 +969,23 @@ impl Backend {
     /// `#[PhpStormStubsElementAvailable]` whose version range excludes
     /// the target version are filtered out during extraction.
     pub fn parse_php_versioned(content: &str, php_version: Option<PhpVersion>) -> Vec<ClassInfo> {
+        Self::parse_php_versioned_with_namespaces(content, php_version)
+            .into_iter()
+            .map(|(cls, _ns)| cls)
+            .collect()
+    }
+
+    /// Like [`parse_php_versioned`] but returns each class together with
+    /// the namespace block it was declared in.
+    ///
+    /// This is needed by [`parse_and_cache_content_versioned`](crate::resolution)
+    /// so that multi-namespace stub files (e.g. PDO.php with both
+    /// `namespace { }` and `namespace Pdo { }`) resolve parent class
+    /// names against the correct namespace context.
+    pub fn parse_php_versioned_with_namespaces(
+        content: &str,
+        php_version: Option<PhpVersion>,
+    ) -> Vec<(ClassInfo, Option<String>)> {
         with_parsed_program(content, "parse_php", |program, content| {
             let mut use_map = HashMap::new();
             Self::extract_use_statements_from_statements(program.statements.iter(), &mut use_map);
@@ -982,13 +999,46 @@ impl Backend {
                 namespace,
             };
 
-            let mut classes = Vec::new();
-            Self::extract_classes_from_statements(
-                program.statements.iter(),
-                &mut classes,
-                Some(&doc_ctx),
-            );
-            classes
+            let mut result: Vec<(ClassInfo, Option<String>)> = Vec::new();
+
+            for statement in program.statements.iter() {
+                match statement {
+                    Statement::Namespace(ns) => {
+                        let block_ns: Option<String> = ns
+                            .name
+                            .as_ref()
+                            .map(|ident| ident.value().to_string())
+                            .filter(|n| !n.is_empty());
+
+                        let mut block_classes = Vec::new();
+                        Self::extract_classes_from_statements(
+                            ns.statements().iter(),
+                            &mut block_classes,
+                            Some(&doc_ctx),
+                        );
+                        for cls in block_classes {
+                            result.push((cls, block_ns.clone()));
+                        }
+                    }
+                    Statement::Class(_)
+                    | Statement::Interface(_)
+                    | Statement::Trait(_)
+                    | Statement::Enum(_) => {
+                        let mut top_classes = Vec::new();
+                        Self::extract_classes_from_statements(
+                            std::iter::once(statement),
+                            &mut top_classes,
+                            Some(&doc_ctx),
+                        );
+                        for cls in top_classes {
+                            result.push((cls, None));
+                        }
+                    }
+                    _ => {}
+                }
+            }
+
+            result
         })
     }
 

src/resolution.rs

@@ -235,18 +235,54 @@ impl Backend {
         uri: &str,
         php_version: Option<PhpVersion>,
     ) -> Option<Vec<Arc<ClassInfo>>> {
-        let mut classes = Self::parse_php_versioned(content, php_version);
         let file_use_map = self.parse_use_statements(content);
         let file_namespace = self.parse_namespace(content);
-        Self::resolve_parent_class_names(&mut classes, &file_use_map, &file_namespace);
+
+        // Parse classes with per-class namespace tracking so that
+        // multi-namespace files (e.g. PDO.php with both `namespace { }`
+        // and `namespace Pdo { }`) resolve parent names correctly.
+        let classes_with_ns = Self::parse_php_versioned_with_namespaces(content, php_version);
+
+        // Group classes by their enclosing namespace and resolve parent
+        // names once per group, mirroring the logic in `update_ast_inner`.
+        let mut classes: Vec<ClassInfo> = Vec::with_capacity(classes_with_ns.len());
+        let mut ns_groups: HashMap<Option<String>, Vec<usize>> = HashMap::new();
+        for (i, (_cls, ns)) in classes_with_ns.iter().enumerate() {
+            ns_groups.entry(ns.clone()).or_default().push(i);
+        }
+
+        // Flatten into a single Vec, preserving original order.
+        for (cls, _) in &classes_with_ns {
+            classes.push(cls.clone());
+        }
+
+        if ns_groups.len() <= 1 {
+            // Single namespace (common case): resolve with file namespace.
+            Self::resolve_parent_class_names(&mut classes, &file_use_map, &file_namespace);
+        } else {
+            // Multi-namespace file: resolve each group with its own
+            // namespace context so that classes in `namespace { }` are
+            // not polluted by a sibling `namespace Pdo { }` block.
+            for (group_ns, indices) in &ns_groups {
+                let mut group: Vec<ClassInfo> =
+                    indices.iter().map(|&i| classes[i].clone()).collect();
+                Self::resolve_parent_class_names(&mut group, &file_use_map, group_ns);
+                for (j, &idx) in indices.iter().enumerate() {
+                    classes[idx] = group[j].clone();
+                }
+            }
+        }
 
         // Set the per-class file_namespace so that classes loaded via
         // PSR-4 / classmap carry their namespace.  This mirrors the
         // same assignment done in `update_ast_inner` for files opened
         // through `did_open` / `did_change`.
-        for cls in &mut classes {
+        for (i, cls) in classes.iter_mut().enumerate() {
             if cls.file_namespace.is_none() {
-                cls.file_namespace = file_namespace.clone();
+                cls.file_namespace = classes_with_ns[i]
+                    .1
+                    .clone()
+                    .or_else(|| file_namespace.clone());
             }
         }
 

tests/completion_inheritance.rs

@@ -1786,3 +1786,91 @@ async fn test_interface_virtual_members_visible_through_parent_chain() {
         _ => panic!("Expected CompletionResponse::Array"),
     }
 }
+
+// ─── Deep inheritance chain through stubs (B8) ──────────────────────────────
+
+/// Methods inherited from `Exception` (like `getCode()`, `getMessage()`) should
+/// be found on a class that extends through a multi-level chain where
+/// intermediate classes live in stubs (e.g. PDOException → RuntimeException →
+/// Exception).
+#[tokio::test]
+async fn test_completion_deep_inheritance_through_stubs() {
+    let backend = create_test_backend();
+
+    let uri = Url::parse("file:///deep_chain.php").unwrap();
+    let text = concat!(
+        "<?php\n",
+        "class QueryException extends \\PDOException {\n",
+        "    public function getSql(): string { return ''; }\n",
+        "}\n",
+        "class DeepChainTest {\n",
+        "    public function handle(QueryException $e): void {\n",
+        "        $e->\n",
+        "    }\n",
+        "}\n",
+    );
+
+    let open_params = DidOpenTextDocumentParams {
+        text_document: TextDocumentItem {
+            uri: uri.clone(),
+            language_id: "php".to_string(),
+            version: 1,
+            text: text.to_string(),
+        },
+    };
+    backend.did_open(open_params).await;
+
+    let completion_params = CompletionParams {
+        text_document_position: TextDocumentPositionParams {
+            text_document: TextDocumentIdentifier { uri },
+            position: Position {
+                line: 6,
+                character: 12,
+            },
+        },
+        work_done_progress_params: WorkDoneProgressParams::default(),
+        partial_result_params: PartialResultParams::default(),
+        context: None,
+    };
+
+    let result = backend.completion(completion_params).await.unwrap();
+    assert!(
+        result.is_some(),
+        "Completion should return results for QueryException"
+    );
+
+    match result.unwrap() {
+        CompletionResponse::Array(items) => {
+            let method_names: Vec<&str> = items
+                .iter()
+                .filter(|i| i.kind == Some(CompletionItemKind::METHOD))
+                .map(|i| i.filter_text.as_deref().unwrap())
+                .collect();
+
+            // Own method
+            assert!(
+                method_names.contains(&"getSql"),
+                "Should include own method 'getSql', got: {:?}",
+                method_names
+            );
+
+            // Methods from Exception (3 levels up: QueryException → PDOException → RuntimeException → Exception)
+            assert!(
+                method_names.contains(&"getMessage"),
+                "Should include 'getMessage' inherited from Exception through deep chain, got: {:?}",
+                method_names
+            );
+            assert!(
+                method_names.contains(&"getCode"),
+                "Should include 'getCode' inherited from Exception through deep chain, got: {:?}",
+                method_names
+            );
+            assert!(
+                method_names.contains(&"getTrace"),
+                "Should include 'getTrace' inherited from Exception through deep chain, got: {:?}",
+                method_names
+            );
+        }
+        _ => panic!("Expected CompletionResponse::Array"),
+    }
+}