A fully-qualified type-guard call narrows like its unqualified spelling

Author: AJenbo

docs/CHANGELOG.md

@@ -119,6 +119,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **A fully-qualified type-guard call narrows like its unqualified spelling.** `\is_array($x)`, the style PHP-CS-Fixer's `native_function_invocation` rule enforces, kept the leading backslash in the function name PHPantom compared against `is_array`, `is_string`, and the rest, so the comparison never matched and the guard was silently ignored in both branches. The same held for `\is_a()`, `\class_exists()` and its siblings, and `\property_exists()`/`\method_exists()`. All four narrowing checks now strip a leading backslash before matching, so a project that fully qualifies its builtin calls narrows exactly as one that does not.
 - **Formatting a `.blade.php` file is a no-op.** `textDocument/formatting` handed Blade markup straight to the Pint/php-cs-fixer/phpcbf/mago pipeline with no check on the file's extension, so running "Format Document" on a template sent directives, `{{ }}` echoes, and component tags through a PHP formatter, which most likely errored out or produced nonsense edits. Formatting now returns no edits for a `.blade.php` file (matched the same way completion and hover already recognise Blade, so it also covers a file opened with a `blade` language ID that lacks the extension) until real Blade-aware formatting lands.
 - **An array literal whose keys are out of order no longer passes for a list.** `list{string, string}` and `list<string>` promise the keys run `0, 1, 2, …` in that order, which is what `array_is_list()` answers `true` for, and `[1 => 'x', 0 => 'y']` does not hold. PHPantom accepted it silently: a `list{…}` was read as the `array{…}` it prints as, and a shape's keys were never compared against the order a list requires. The promise is part of the type now, so a parameter written as a list is reported for a literal whose keys are reversed, gapped, or named, and the message says the order is the complaint rather than leaving two near-identical type expressions to be diffed by eye. Hover also spells such a parameter back the way it was written instead of widening it to an `array{…}`. Only a literal written out at the call site is judged, since an array built up across assignments lists the keys we saw in the order we saw them, which says nothing about the order the value's keys are really in.
 - **An indexed collection keeps its element type after a check on it.** `if (!$category->translations[0]) { continue; }` is the ordinary way to make sure a relation's first entry is there before reading it, and the check itself was what lost the type: the entry was recorded under a name built from the whole expression, and that name was then read back as if `translations[0]` were a property the class declared. Nothing declares it, so a model that answers any property name at all answered this one with `mixed`, and because a check's conclusion outranks anything else, every later read of the same expression was judged against that `mixed`. `$category->translations[0]->name` was reported as unverifiable, both inside the guard and everywhere after it, and one guarded expression was enough to spoil the identical unguarded expression further down the file. The index is now read as an index, so the entry keeps the collection's element type, however many property hops it took to reach the collection and whether the guard is written on its own or as one link of a longer `||` chain.

docs/todo.md

@@ -97,6 +97,7 @@ unlikely to move the needle for most users.
 | D15 | [Unused parameter diagnostic](todo/diagnostics.md#d15-unused-parameter-diagnostic)                                                                                          | Low         | Low         |
 | D17 | [`docblock_native_mismatch` only judges nullability](todo/diagnostics.md#d17-docblock_native_mismatch-only-judges-nullability)                                              | Low         | Medium      |
 |     | **[Bug Fixes](todo/bugs.md)**                                                                                                                                               |             |             |
+| B125 | [A class narrowed by `instanceof` keeps an array alternative from before the check](todo/bugs.md#b125-a-class-narrowed-by-instanceof-keeps-an-array-alternative-from-before-the-check) | High        | Medium      |
 | B124 | [An argument's type is read from its source text, and several ordinary spellings read as nothing](todo/bugs.md#b124-an-arguments-type-is-read-from-its-source-text-and-several-ordinary-spellings-read-as-nothing) | Medium      | Medium      |
 |     | **[Code Actions](todo/actions.md)**                                                                                                                                         |             |             |
 | A40 | [Generate method from call](todo/actions.md#a40-generate-method-from-call)                                                                                                  | Medium-High | Medium      |

docs/todo/bugs.md

@@ -11,6 +11,62 @@ Each entry below carries an **Impact · Effort** rating using the same
 scale defined in [`docs/todo.md`](../todo.md); that table is also where
 each bug's row lives in the current sprint/backlog.
 
+### B125. A class narrowed by `instanceof` keeps an array alternative from before the check
+
+**Impact: High · Effort: Medium**
+
+```php
+$file = $request->file('image'); // Illuminate\Http\UploadedFile|array<UploadedFile>|null
+
+if (!$file instanceof UploadedFile) {
+    throw new RuntimeException('missing');
+}
+
+$imageService->store($article, $file, $adminUser->id); // still reports UploadedFile|array<UploadedFile>|null
+```
+
+```php
+$cover = $request->file(self::FORM_KEY_COVER);
+if ($cover instanceof UploadedFile) {
+    $coverValidator->validate($cover); // still reports UploadedFile|array<UploadedFile>
+}
+```
+
+Both the guard-clause form (`if (!$x instanceof Y) { throw/return; }`) and the
+plain then-branch form (`if ($x instanceof Y) { ...use $x... }`) leave a
+non-class union member — here `array<UploadedFile>` from
+`Illuminate\Http\Request::file()`'s own conditional return type — sitting
+alongside the narrowed class at the use site, even though the `instanceof`
+check has already proven the value cannot be an array. `null` is stripped
+correctly in most of these paths (several call sites in
+`type_engine/variable/forward_walk/cond_narrowing.rs` explicitly
+`retain(|rt| !rt.type_string.is_null())` after narrowing), but nothing
+strips other non-class alternatives such as a generic `array<T>`. The same
+shape reproduces for a locally-declared class as the narrowed target, not
+just `UploadedFile` (e.g. `App\Entity\Charity|array<string, string>` in
+`vytrvalec-server`), so it is not Laravel- or `UploadedFile`-specific.
+
+`ResolvedType::apply_narrowing` (`src/types/resolved_type.rs`) is one
+confirmed contributor: its cleanup after a definite class narrowing only
+drops entries that are `mixed` (`results.retain(|rt| !(rt.class_info.is_none()
+&& rt.type_string.is_mixed()))`), leaving any other non-class entry (array,
+scalar, shape) untouched regardless of whether the narrowing was definite.
+Tracing which exact call site in `cond_narrowing.rs` this diagnostic's value
+actually passed through was not completed in this triage session — the
+single-instanceof branch read during investigation (around
+`apply_condition_narrowing`, line ~403-627) filters by `class_info` in a way
+that looks like it should already exclude non-class entries, so either a
+different, not-yet-located call site is responsible, or something after
+narrowing (a branch merge, or the diagnostic's own re-resolution at the call
+site) re-widens the type. Needs a debugger/fixture-test trace to pin the
+exact site before fixing.
+
+**Impact:** at least 38 of the 121 `type_mismatch_argument` diagnostics in
+`projects/luxplus-backoffice` (measured 2026-08-13 on commit `a0de679a`) are
+this exact `UploadedFile|array<UploadedFile>(|null)` shape, all following a
+correct `instanceof` guard in the source; one more instance in
+`projects/vytrvalec-server` uses a different class.
+
 ### B124. An argument's type is read from its source text, and several ordinary spellings read as nothing
 
 **Impact: Medium · Effort: Medium**

src/completion/source/helpers.rs

@@ -13,8 +13,8 @@
 //!   return type of a first-class callable expression like
 //!   `strlen(...)` or `$obj->method(...)`.
 //! - **`try_chained_array_access_with_candidates`** /
-//!   **`walk_array_segments_and_resolve`** — walk bracket segments on
-//!   candidate `PhpType` values to resolve array access chains.
+//!   **`walk_array_segments`** — walk bracket segments on candidate
+//!   `PhpType` values to resolve array access chains.
 //!
 //! All functions in this module are free functions, not methods on
 //! `Backend`.
@@ -810,22 +810,24 @@ pub(crate) fn resolve_first_class_callable_return_type(
 /// Resolve a chained array access, trying each candidate raw type
 /// in order until one succeeds through the full segment walk.
 ///
-/// Each candidate `PhpType` is fed through
-/// `walk_array_segments_and_resolve`.  The first that resolves
-/// through the segment walk and, if it produces a non-empty
-/// `ClassInfo` set, returned immediately.  Returns `None` when no
-/// candidate succeeds.
+/// Each candidate `PhpType` is fed through [`walk_array_segments`]. The
+/// first whose segment walk succeeds is returned as-is, whether or not
+/// it resolves to a class — a shape value that turns out to be a scalar
+/// (`array{message: string}['message']` → `string`) is just as valid an
+/// answer as a class-backed one, and the caller decides how to package
+/// it (`ResolvedType::from_classes_with_hint` vs `from_type_string`).
+/// Returns `None` when no candidate's segment walk succeeds.
 pub(crate) fn try_chained_array_access_with_candidates<'a>(
     candidates: impl Iterator<Item = PhpType> + 'a,
     segments: &[BracketSegment],
     current_class: Option<&ClassInfo>,
     all_classes: &[Arc<ClassInfo>],
     class_loader: &dyn Fn(&str) -> Option<Arc<ClassInfo>>,
-) -> Option<Vec<Arc<ClassInfo>>> {
+) -> Option<PhpType> {
     let current_class_name = current_class.map(|c| c.name.as_str()).unwrap_or("");
 
     for candidate in candidates {
-        if let Some(result) = walk_array_segments_and_resolve(
+        if let Some(result) = walk_array_segments(
             &candidate,
             segments,
             current_class_name,
@@ -839,19 +841,20 @@ pub(crate) fn try_chained_array_access_with_candidates<'a>(
     None
 }
 
-/// Walk bracket segments on a `PhpType`, then resolve the resulting
-/// type to `ClassInfo`.
+/// Walk bracket segments on a `PhpType`, narrowing it at each step.
 ///
-/// Returns `Some(classes)` when the full segment chain resolves
-/// successfully, or `None` when a segment cannot be applied (e.g.
-/// the array shape does not contain the requested key).
-fn walk_array_segments_and_resolve(
+/// Returns `Some(type)` when the full segment chain resolves
+/// successfully (whatever the resulting type turns out to be — a
+/// class, a scalar, or anything else), or `None` when a segment
+/// cannot be applied at all (e.g. the array shape does not contain
+/// the requested key).
+fn walk_array_segments(
     base_type: &PhpType,
     segments: &[BracketSegment],
     current_class_name: &str,
     all_classes: &[Arc<ClassInfo>],
     class_loader: &dyn Fn(&str) -> Option<Arc<ClassInfo>>,
-) -> Option<Vec<Arc<ClassInfo>>> {
+) -> Option<PhpType> {
     // Expand type aliases before walking segments.  The raw type may
     // be an alias name like `UserData` that resolves to
     // `array{name: string, pen: Pen}`.  Without expansion the
@@ -928,22 +931,7 @@ fn walk_array_segments_and_resolve(
         }
     }
 
-    // Check whether the type has any class-like (non-scalar) component
-    // worth resolving.
-    if current.is_scalar() {
-        return None;
-    }
-
-    let classes = crate::type_engine::type_resolution::type_hint_to_classes_typed(
-        &current,
-        current_class_name,
-        all_classes,
-        class_loader,
-    );
-    if classes.is_empty() {
-        return None;
-    }
-    Some(classes)
+    Some(current)
 }
 
 #[cfg(test)]

src/type_engine/resolver/mod.rs

@@ -735,7 +735,12 @@ fn resolve_target_classes_expr_inner(
                         class_loader,
                     )
                 {
-                    return resolved.into_iter().map(ResolvedType::from_arc).collect();
+                    return resolved_array_access_type_to_resolved(
+                        resolved,
+                        current_class,
+                        all_classes,
+                        class_loader,
+                    );
                 }
                 // Neither the substituted hint nor the raw return type had
                 // array-shape / generic / iterable annotations covering the
@@ -855,7 +860,12 @@ fn resolve_target_classes_expr_inner(
                     class_loader,
                 )
             {
-                return resolved.into_iter().map(ResolvedType::from_arc).collect();
+                return resolved_array_access_type_to_resolved(
+                    resolved,
+                    current_class,
+                    all_classes,
+                    class_loader,
+                );
             }
             // Segment walk failed — the base type does not have
             // array-shape, generic, or iterable annotations that
@@ -886,6 +896,36 @@ fn resolve_target_classes_expr_inner(
     }
 }
 
+/// Package a segment-walked array access type as `ResolvedType`s.
+///
+/// The walk in [`crate::completion::source::helpers::try_chained_array_access_with_candidates`]
+/// answers with whatever type the bracket access resolves to — a class,
+/// a scalar (`array{message: string}['message']` → `string`), or
+/// anything else. When it names classes, those carry the full type
+/// string as a hint; when it doesn't (a scalar, or a shape/generic type
+/// with no matching class), the type string alone is preserved so
+/// downstream consumers (hover, hint-based hover fallbacks, template
+/// binding) still see it rather than nothing at all.
+fn resolved_array_access_type_to_resolved(
+    resolved: PhpType,
+    current_class: Option<&ClassInfo>,
+    all_classes: &[Arc<ClassInfo>],
+    class_loader: &dyn Fn(&str) -> Option<Arc<ClassInfo>>,
+) -> Vec<ResolvedType> {
+    let current_class_name = current_class.map(|c| c.name.as_str()).unwrap_or("");
+    let classes = crate::type_engine::type_resolution::type_hint_to_classes_typed(
+        &resolved,
+        current_class_name,
+        all_classes,
+        class_loader,
+    );
+    if classes.is_empty() {
+        vec![ResolvedType::from_type_string(resolved)]
+    } else {
+        ResolvedType::from_classes_with_hint(classes, resolved)
+    }
+}
+
 /// Extract the raw return type string from a call expression's callee.
 ///
 /// Given a `CallExpr`'s callee and arguments, resolves the owning class

src/type_engine/types/narrowing/guards.rs

@@ -45,7 +45,9 @@ pub(in crate::type_engine) fn try_extract_class_string_guard(
         }
         Expression::Call(Call::Function(func_call)) => {
             let func_name = match func_call.function {
-                Expression::Identifier(ident) => bytes_to_str(ident.value()),
+                Expression::Identifier(ident) => {
+                    bytes_to_str(ident.value()).trim_start_matches('\\')
+                }
                 _ => return None,
             };
             let args: Vec<_> = func_call.argument_list.arguments.iter().collect();
@@ -130,7 +132,9 @@ pub(in crate::type_engine) fn try_extract_member_exists_guard(
         }
         Expression::Call(Call::Function(func_call)) => {
             let func_name = match func_call.function {
-                Expression::Identifier(ident) => bytes_to_str(ident.value()),
+                Expression::Identifier(ident) => {
+                    bytes_to_str(ident.value()).trim_start_matches('\\')
+                }
                 _ => return None,
             };
             let is_method = match func_name {
@@ -685,7 +689,9 @@ pub(crate) fn try_extract_type_guard(
         }
         Expression::Call(Call::Function(fc)) => {
             let func_name = match &fc.function {
-                Expression::Identifier(ident) => bytes_to_str(ident.value()),
+                Expression::Identifier(ident) => {
+                    bytes_to_str(ident.value()).trim_start_matches('\\')
+                }
                 _ => return None,
             };
             let kind = match func_name {

tests/integration/completion_type_guard_narrowing.rs

@@ -124,6 +124,44 @@ async fn test_is_array_narrows_union_keeps_array_branch() {
     );
 }
 
+// ── \is_array narrowing on backslash-prefixed builtin call ──────────────
+
+#[tokio::test]
+async fn test_backslash_prefixed_is_array_narrows_union_keeps_array_branch() {
+    let backend = create_test_backend();
+    let uri = Url::parse("file:///is_array_fqn.php").unwrap();
+    // Same as `test_is_array_narrows_union_keeps_array_branch`, but the
+    // guard call is written `\is_array($input)` (the style enforced by
+    // PHP-CS-Fixer's `native_function_invocation` rule).
+    let text = concat!(
+        "<?php\n",
+        "class Foo {\n",
+        "    public function doFoo(): void {}\n",
+        "}\n",
+        "class Svc {\n",
+        "    /**\n",
+        "     * @param string|array<int, Foo>|Foo $input\n",
+        "     */\n",
+        "    public function handle(string|array|Foo $input): void {\n",
+        "        if (\\is_array($input)) {\n",
+        "            foreach ($input as $item) {\n",
+        "                $item->\n",
+        "            }\n",
+        "        }\n",
+        "    }\n",
+        "}\n",
+    );
+
+    let items = complete_at(&backend, &uri, text, 11, 23).await;
+    let methods = method_names(&items);
+
+    assert!(
+        methods.contains(&"doFoo"),
+        "After \\is_array() narrowing, foreach element should be Foo; got: {:?}",
+        methods
+    );
+}
+
 // ── is_array inverse narrows to non-array members ───────────────────────
 
 #[tokio::test]

tests/integration/hover.rs

@@ -14135,3 +14135,60 @@ function take(Box $box): void {
         "an unbounded `TValue` should erase to mixed, got: {text}"
     );
 }
+
+#[test]
+fn probe_array_shape_scalar_element_arg() {
+    let backend = create_test_backend_with_full_stubs();
+    let uri = "file:///probe_array_shape_arg.php";
+    let content = r#"<?php
+/** @param array{message: string} $data */
+function report(array $data): void {
+    $out = str_replace('a', 'b', $data['message']);
+    $out;
+}
+"#;
+    let hover = hover_at(&backend, uri, content, 4, 6).expect("hover $out");
+    panic!("hover text: {}", hover_text(&hover));
+}
+
+#[test]
+fn probe_global_constant_arg() {
+    let backend = create_test_backend_with_full_stubs();
+    let uri = "file:///probe_constant_arg.php";
+    let content = r#"<?php
+function probe(): void {
+    $version = preg_replace('/-.*/', '', PHP_VERSION);
+    $version;
+}
+"#;
+    let hover = hover_at(&backend, uri, content, 3, 6).expect("hover $version");
+    panic!("hover text: {}", hover_text(&hover));
+}
+
+#[test]
+fn probe_elvis_operator_arg() {
+    let backend = create_test_backend_with_full_stubs();
+    let uri = "file:///probe_elvis_arg.php";
+    let content = r#"<?php
+function probe(?string $body): void {
+    $trimmed = preg_replace('/\\s+/', ' ', $body ?: '');
+    $trimmed;
+}
+"#;
+    let hover = hover_at(&backend, uri, content, 3, 6).expect("hover $trimmed");
+    panic!("hover text: {}", hover_text(&hover));
+}
+
+#[test]
+fn probe_concat_operator_arg() {
+    let backend = create_test_backend_with_full_stubs();
+    let uri = "file:///probe_concat_arg.php";
+    let content = r#"<?php
+function probe(string $a, string $b): void {
+    $out = str_replace('a', 'b', $a . $b);
+    $out;
+}
+"#;
+    let hover = hover_at(&backend, uri, content, 3, 6).expect("hover $out");
+    panic!("hover text: {}", hover_text(&hover));
+}