Fix flaky resolve on shadowed classes

Author: AJenbo

docs/CHANGELOG.md

@@ -42,6 +42,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - **Facade static calls keep concrete method return types.** Static calls on Laravel-style facades now resolve missing methods through `getFacadeAccessor()` and facade `@mixin` targets before falling back to `__callStatic()`, so values like `Driver::details()` keep the concrete provider method return type instead of degrading to the facade's broad magic-call return. Contributed by @calebdw.
 - **`class-string<static>` parameters no longer reject sibling subclass constants.** Static helper calls from a shared base class that pass concrete `::class` constants for sibling subclasses no longer report false argument-type mismatches against `class-string<static>`. Contributed by @calebdw.
+- **Built-in PHP classes shadowed by vendor polyfills resolve to the real definition.** When an installed package ships a polyfill for a PHP built-in (for example symfony/polyfill-php84's `RoundingMode`), resolution sometimes picked the polyfill's legacy pre-enum declaration instead of the built-in, turning enum cases into plain int constants and reporting false "expects RoundingMode, got int" argument mismatches. Which declaration won could change from one run to the next, making whole-project analysis results nondeterministic. Global names of built-in classes now always resolve to the bundled PHP definition, and classes discovered inside phar archives are indexed in a stable order.
 - **Member name positions no longer suggest classes.** Typing a name after `function`, `const`, or enum `case` (for example `protected function getC`) no longer offers unrelated class names from the project. Property names were already safe because they start with `$`. Contributed by @calebdw.
 - **Null-initialized variables reassigned in an untyped foreach are not stuck as `null`.** When the iterable has no known element type (for example an untyped parameter), the loop value is now treated as `mixed`, so `$x = $value` after `$x = null` participates in post-loop merge and `is_null` early-return narrowing instead of leaving a false `null` type at later call sites. Contributed by @calebdw.
 - **By-reference method out-parameters no longer flag undefined variables.** Passing an undeclared variable into a by-ref parameter (e.g. `new A()->dosmth($y, $foo)` where `$foo` is `&$x`) is valid PHP and now defines the variable for later use, matching free functions like `preg_match(..., $matches)` and `$this->method($out)`. Contributed by @calebdw.

docs/todo.md

@@ -106,6 +106,7 @@ unlikely to move the needle for most users.
 | D15 | [Unused parameter diagnostic](todo/diagnostics.md#d15-unused-parameter-diagnostic)                                                                                          | Low         | Low         |
 |     | **[Bug Fixes](todo/bugs.md)**                                                                                                                                               |             |             |
 | B1  | [`resolve_function_name` guesses a single namespace, missing same-file multi-namespace declarations](todo/bugs.md#b1-resolve_function_name-guesses-a-single-namespace-missing-same-file-multi-namespace-declarations) | Low-Medium  | Medium      |
+| B2  | [`self::`/`static::` inside macro closures resolve to the enclosing class, not the macro target](todo/bugs.md#b2-selfstatic-inside-macro-closures-resolve-to-the-enclosing-class-not-the-macro-target) | Medium      | Medium      |
 |     | **[Code Actions](todo/actions.md)**                                                                                                                                         |             |             |
 | A40 | [Generate method from call](todo/actions.md#a40-generate-method-from-call)                                                                                                  | Medium-High | Medium      |
 | A41 | [Create class from non-existing name](todo/actions.md#a41-create-class-from-non-existing-name)                                                                              | Medium      | Medium      |

docs/todo/bugs.md

@@ -40,3 +40,32 @@ Fixing this requires either threading the call expression's byte
 offset through to `resolve_function_name` or adding an offset-aware
 variant of the loader closure. Size the fix accordingly — this is not
 a one-line change.
+
+## B2. `self::`/`static::` inside macro closures resolve to the enclosing class, not the macro target
+
+Inside a closure passed to `Target::macro(...)` (Laravel `Macroable`
+or Carbon), `$this` correctly resolves to the macro target class via
+`laravel_macro_this_resolver` (`closure_this_from_static_receiver` in
+`src/completion/variable/closure_resolution.rs`). But `self::` and
+`static::` inside the same closure still resolve to the class that
+lexically encloses the registration (e.g. the service provider), so
+Carbon's static macro idiom
+
+```php
+CarbonImmutable::macro('diffFromYear', function (int $year): string {
+    return self::this()->diffForHumans(...);
+});
+```
+
+reports a false `Method 'this' not found on class
+'App\Providers\DemoServiceProvider'` (`unknown_member`). At runtime
+both `Macroable::__call`/`__callStatic` and Carbon bind the closure
+with the target as scope, so `self`/`static` refer to the target and
+protected members like `Carbon\Traits\Mixin::this()` are accessible.
+
+Subject resolution for `Self_`/`Static` needs the same "am I inside a
+macro registration closure?" awareness that `$this` resolution already
+has. The `self::this()` demo in
+`examples/laravel/app/Providers/DemoServiceProvider.php` was switched
+to the supported `$this->` form when this was discovered; restore the
+static idiom there once fixed.

examples/laravel/app/Providers/DemoServiceProvider.php

@@ -23,9 +23,11 @@ public function boot(): void
         // PHPantom recovers those from CollectionMixin's source.
         Collection::mixin(new CollectionMixin());
 
-        // Carbon supports the same `macro()` pattern as Laravel's Macroable:
+        // Carbon supports the same `macro()` pattern as Laravel's Macroable.
+        // `$this` inside the closure is the CarbonImmutable instance the
+        // macro is called on:
         CarbonImmutable::macro('diffFromYear', function (int $year, bool $absolute = false): string {
-            return self::this()->diffForHumans(
+            return $this->diffForHumans(
                 CarbonImmutable::create($year, 1, 1),
                 ['syntax' => \Carbon\CarbonInterface::DIFF_ABSOLUTE]
             );

src/phar.rs

@@ -23,6 +23,13 @@ pub(crate) struct PharArchive {
     data: Vec<u8>,
     /// Map of internal file path → (offset into `data`, uncompressed size).
     files: HashMap<String, (usize, usize)>,
+    /// Internal file paths in manifest order.  Iteration must be
+    /// deterministic: consumers register discovered classes
+    /// first-wins, so a randomized `HashMap` order would make it
+    /// nondeterministic which file resolves a class name that is
+    /// declared in several files of the archive (e.g. the enum and
+    /// legacy-class variants of a symfony polyfill).
+    paths: Vec<String>,
 }
 
 impl PharArchive {
@@ -115,6 +122,7 @@ impl PharArchive {
         let data_area_start = manifest_end;
 
         let mut files = HashMap::with_capacity(file_count);
+        let mut paths = Vec::with_capacity(file_count);
         let mut offset = data_area_start;
 
         for entry in &entries {
@@ -123,12 +131,17 @@ impl PharArchive {
                 if offset + entry.compressed_size > data.len() {
                     return None;
                 }
-                files.insert(entry.filename.clone(), (offset, entry.uncompressed_size));
+                if files
+                    .insert(entry.filename.clone(), (offset, entry.uncompressed_size))
+                    .is_none()
+                {
+                    paths.push(entry.filename.clone());
+                }
             }
             offset += entry.compressed_size;
         }
 
-        Some(Self { data, files })
+        Some(Self { data, files, paths })
     }
 
     /// Extract the content of a file inside the phar.
@@ -137,9 +150,9 @@ impl PharArchive {
         self.data.get(offset..offset + size)
     }
 
-    /// Iterate over all file paths in the archive.
+    /// Iterate over all file paths in the archive, in manifest order.
     pub fn file_paths(&self) -> impl Iterator<Item = &str> {
-        self.files.keys().map(String::as_str)
+        self.paths.iter().map(String::as_str)
     }
 }
 
@@ -295,6 +308,20 @@ mod tests {
         assert_eq!(paths, vec!["a.php", "b.php", "c.php"]);
     }
 
+    #[test]
+    fn file_paths_preserves_manifest_order() {
+        let phar_bytes = build_test_phar(&[
+            ("zeta.php", b"<?php // z"),
+            ("alpha.php", b"<?php // a"),
+            ("mid.php", b"<?php // m"),
+        ]);
+
+        let archive = PharArchive::parse(phar_bytes).expect("should parse");
+
+        let paths: Vec<&str> = archive.file_paths().collect();
+        assert_eq!(paths, vec!["zeta.php", "alpha.php", "mid.php"]);
+    }
+
     #[test]
     fn parse_returns_none_for_garbage() {
         assert!(PharArchive::parse(vec![0, 1, 2, 3]).is_none());

src/resolution.rs

@@ -321,6 +321,26 @@ impl Backend {
             return Some(cls);
         }
 
+        // ── Phase 0.5: built-in names resolve to the embedded stubs ──
+        // A global-namespace class name that exists in the embedded
+        // stub index is a PHP built-in (core or bundled extension).
+        // Vendor code can only redeclare such a name inside a
+        // conditional block: a polyfill mirroring the built-in for
+        // older runtimes.  symfony/polyfill-php84, for example, ships
+        // two `RoundingMode` declarations — an enum and a pre-enum
+        // class whose "cases" are plain int constants.  Resolving the
+        // name through the classmap (Phase 1) would pick whichever
+        // polyfill file happened to be indexed first, which is
+        // nondeterministic when several files declare the name and
+        // wrong whenever a legacy variant wins (enum cases would
+        // resolve to int constants).  The stub is the authoritative
+        // definition of a built-in, so it wins over classmap entries.
+        if expected_ns.is_none()
+            && let Some(cls) = self.load_stub_class(last_segment)
+        {
+            return Some(cls);
+        }
+
         // ── Phase 1: Try the fqn_uri_index (FQN → URI) ───────────
         // The fqn_uri_index is populated by `scan_autoload_files` (Composer
         // `autoload_files.php` entries and their `require_once` chains),

tests/integration/diagnostics_type_errors.rs

@@ -6317,3 +6317,59 @@ function test(): void {
         "A string literal value in a list that is NOT a property should be flagged"
     );
 }
+
+// ─── Built-in names shadowed by vendor polyfills ─────────────────────────────
+
+/// A vendor polyfill (e.g. symfony/polyfill-php84) may declare a legacy
+/// `final class RoundingMode` whose "cases" are plain int constants,
+/// registered in the classmap alongside the real built-in enum.  The
+/// embedded stub must win: `RoundingMode::HalfAwayFromZero` passed to a
+/// `RoundingMode` parameter is an enum case, not an int.
+#[test]
+fn builtin_enum_case_prefers_stub_over_polyfill_classmap_entry() {
+    let backend = create_test_backend_with_full_stubs();
+
+    // Simulate the polyfill's legacy-class variant on disk, registered
+    // in the classmap under the built-in's global name.
+    let dir = tempfile::tempdir().expect("failed to create temp dir");
+    let polyfill = dir.path().join("RoundingMode.php");
+    std::fs::write(
+        &polyfill,
+        concat!(
+            "<?php\n",
+            "if (\\PHP_VERSION_ID < 80100) {\n",
+            "    final class RoundingMode\n",
+            "    {\n",
+            "        const HalfAwayFromZero = 0;\n",
+            "        const HalfTowardsZero = 1;\n",
+            "        const HalfEven = 2;\n",
+            "    }\n",
+            "}\n",
+        ),
+    )
+    .expect("failed to write polyfill file");
+    {
+        let mut idx = backend.fqn_uri_index().write();
+        idx.insert(
+            "RoundingMode".to_string(),
+            Url::from_file_path(&polyfill).unwrap().to_string(),
+        );
+    }
+
+    let php = r#"<?php
+function takes_mode(RoundingMode $mode): void {}
+
+function test(): void {
+    takes_mode(RoundingMode::HalfAwayFromZero);
+}
+"#;
+    let uri = "file:///test.php";
+    backend.update_ast(uri, php);
+    let mut out = Vec::new();
+    backend.collect_argument_type_diagnostics(uri, php, &mut out);
+    assert!(
+        !has_type_error(&out),
+        "Enum case of a built-in must resolve to the enum, not the polyfill's int constant: {:?}",
+        type_error_messages(&out)
+    );
+}