Index vendor packages with custom autoloaders and prefer PSR-4 classmap

files

Author: AJenbo

docs/CHANGELOG.md

@@ -28,6 +28,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Eloquent `$dates` and `where{Property}` go-to-definition.** Ctrl+clicking a property backed by the `$dates` array now jumps to the string entry inside `$dates`, matching the behaviour already supported for `$casts`, `$attributes`, `$fillable`, `$guarded`, `$hidden`, `$visible`, and `$appends`. Ctrl+clicking a `where{Property}()` dynamic method (e.g. `whereFlour`, `whereKitchenId`) now jumps to the corresponding column entry in whichever Eloquent array defines that column.
 - **Property `self`/`static` type resolution.** Properties declared with `@var self|null` or `static` type annotations now resolve to the owning class name instead of displaying the raw `self`/`static` keyword in hover and type inference.
 - **Magic `__get` property access.** Accessing undefined properties on objects with a `__get` method now resolves to the method's declared return type, even when `__get` has no template parameters (e.g. `SimpleXMLElement::$child` resolves to `SimpleXMLElement`).
+- **By-reference out-parameters no longer flagged as unused.** Variables passed to functions with known by-reference out-parameters (e.g. `getmxrr($domain, $hosts)`, `preg_match($pattern, $subject, $matches)`) are now treated as used, eliminating false-positive unused-variable diagnostics.
+- **Composer `files` autoload packages now indexed.** Vendor packages that register a custom autoloader via `spl_autoload_register` in their `"autoload": {"files": [...]}` entries now have their entire package directory scanned for classes, fixing "Class not found" diagnostics for packages like `dms/phpunit-arraysubset-asserts`.
+- **Classmap collision resolution.** When two files in the same package declare the same fully-qualified class name (e.g. conditional loading with a normal and empty variant), the file whose name matches the class name (PSR-4 convention) is now preferred.
 - **Magic `__call` method return type.** Calling undefined methods on objects with a `__call` method now resolves to `__call`'s declared return type for hover and type inference.
 - **SoapClient arbitrary methods.** Calling any method on `SoapClient` (or subclasses) no longer produces false-positive "unknown member" diagnostics. SoapClient is a SOAP proxy where any method name is valid at runtime.
 - **Property narrowing in type error diagnostics.** Properties narrowed via `instanceof` checks (e.g. `if ($this->service instanceof MockInterface)`) now use the narrowed type when checking argument compatibility, eliminating false positives in test code that uses Mockery or similar patterns.

src/classmap_scanner.rs

@@ -355,6 +355,38 @@ pub fn scan_vendor_packages_with_skip(
             }
         }
 
+        // Files entries (individual PHP files that are always loaded)
+        if let Some(files) = autoload.get("files").and_then(|f| f.as_array()) {
+            let mut has_custom_autoloader = false;
+            for entry in files {
+                if let Some(file_str) = entry.as_str() {
+                    let file = pkg_path.join(file_str);
+                    if file.is_file()
+                        && file.extension().is_some_and(|ext| ext == "php")
+                        && !skip_paths.contains(&file)
+                    {
+                        // Check if this file registers a custom autoloader.
+                        if !has_custom_autoloader
+                            && let Ok(content) = std::fs::read(&file)
+                            && memmem::find(&content, b"spl_autoload_register").is_some()
+                        {
+                            has_custom_autoloader = true;
+                        }
+                        plain_files.push(file);
+                    }
+                }
+            }
+
+            // When a files entry registers a custom autoloader via
+            // spl_autoload_register, it will load classes from the
+            // package at runtime. Since we can't execute that logic,
+            // do a full scan of the package directory to discover all
+            // classes it provides.
+            if has_custom_autoloader {
+                collect_php_files(&pkg_path, &vendor_dir_paths, skip_paths, &mut plain_files);
+            }
+        }
+
         // Classmap entries
         if let Some(cm) = autoload.get("classmap").and_then(|c| c.as_array()) {
             for entry in cm {
@@ -544,7 +576,19 @@ fn scan_files_parallel_full(files: &[PathBuf]) -> WorkspaceScanResult {
             if let Ok(content) = std::fs::read(path) {
                 let scan = find_symbols(&content);
                 for fqcn in scan.classes {
-                    result.classmap.entry(fqcn).or_insert_with(|| path.clone());
+                    let class_short_name = fqcn_short_name(&fqcn).to_owned();
+                    result
+                        .classmap
+                        .entry(fqcn)
+                        .and_modify(|existing| {
+                            let existing_stem =
+                                existing.file_stem().and_then(|s| s.to_str()).unwrap_or("");
+                            let new_stem = path.file_stem().and_then(|s| s.to_str()).unwrap_or("");
+                            if existing_stem != class_short_name && new_stem == class_short_name {
+                                *existing = path.clone();
+                            }
+                        })
+                        .or_insert_with(|| path.clone());
                 }
                 for fqn in scan.functions {
                     result
@@ -602,7 +646,25 @@ fn scan_files_parallel_full(files: &[PathBuf]) -> WorkspaceScanResult {
     for batch in results {
         for (scan, path) in batch {
             for fqcn in scan.classes {
-                result.classmap.entry(fqcn).or_insert_with(|| path.clone());
+                let class_short_name = fqcn_short_name(&fqcn).to_owned();
+                result
+                    .classmap
+                    .entry(fqcn)
+                    .and_modify(|existing| {
+                        // When two files declare the same FQN, prefer the one
+                        // whose filename matches the class's short name (PSR-4
+                        // convention). This handles packages with conditional
+                        // loading (e.g. ArraySubsetAsserts.php vs
+                        // ArraySubsetAssertsEmpty.php both defining the same
+                        // trait name).
+                        let existing_stem =
+                            existing.file_stem().and_then(|s| s.to_str()).unwrap_or("");
+                        let new_stem = path.file_stem().and_then(|s| s.to_str()).unwrap_or("");
+                        if existing_stem != class_short_name && new_stem == class_short_name {
+                            *existing = path.clone();
+                        }
+                    })
+                    .or_insert_with(|| path.clone());
             }
             for fqn in scan.functions {
                 result
@@ -1665,6 +1727,14 @@ fn normalise_prefix(prefix: &str) -> String {
     }
 }
 
+/// Extract the short (unqualified) class name from a fully-qualified name.
+///
+/// For example, `"DMS\\PHPUnitExtensions\\ArraySubset\\ArraySubsetAsserts"`
+/// yields `"ArraySubsetAsserts"`.
+fn fqcn_short_name(fqcn: &str) -> &str {
+    fqcn.rsplit('\\').next().unwrap_or(fqcn)
+}
+
 /// Extract string values from a JSON value that is either a single
 /// string or an array of strings.
 fn value_to_strings(value: &serde_json::Value) -> Vec<String> {