Add report-magic-properties config option and diagnostic support

Author: AJenbo

config-schema.json

@@ -29,6 +29,11 @@
           "type": "boolean",
           "description": "Report calls that pass more arguments than the function accepts. PHP silently ignores extra arguments to user-defined functions, and many libraries exploit this for flexible APIs.",
           "default": false
+        },
+        "report-magic-properties": {
+          "type": "boolean",
+          "description": "Report unknown property access on classes with __get when virtual properties are defined (via @property docblock tags, Laravel Eloquent column inference, or other providers). Matches PHPStan's reportMagicProperties behaviour.",
+          "default": false
         }
       }
     },

docs/CHANGELOG.md

@@ -38,6 +38,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **`global` keyword variable resolution.** Variables imported with `global $var` now resolve to their top-level type, enabling completion, hover, and go-to-definition.
 - **`array_reduce`, `array_sum`, and `array_product` return type inference.** `array_reduce()` resolves to the type of its initial value argument. `array_sum()` and `array_product()` resolve to `int|float`.
 - **Machine-readable CLI output.** Both `analyze` and `fix` accept a `--format` flag with `table`, `github`, and `json` options. When `GITHUB_ACTIONS` is set, table output automatically includes GitHub annotations.
+- **Magic property diagnostics.** New `report-magic-properties` option under `[diagnostics]` in `.phpantom.toml`. When enabled, classes with `__get` that also have virtual properties (from `@property` docblock tags, Laravel Eloquent column inference, or other providers) will flag unknown property access instead of silently allowing it.
 
 ### Changed
 
@@ -52,7 +53,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
-- **Blade diagnostics in `analyze` command.** Blade template files now receive full diagnostics (unknown members, unknown classes, unused variables, etc.) when running `phpantom_lsp analyze`. Previously, the analyzer passed raw Blade template content to diagnostic collectors instead of the preprocessed virtual PHP, so no diagnostics were produced.
+- **Blade diagnostics in `analyze` command.** Blade template files now receive full diagnostics (unknown members, unknown classes, unused variables, etc.) when running `phpantom_lsp analyze`.
 - **Blade unknown-member diagnostic positions.** Unknown-member diagnostics in Blade files now point to the correct line in the original template instead of the virtual PHP line number.
 - **Spurious function auto-imports.** Import statements like `use function is_array;` were misidentified as function declarations, polluting the completion list with phantom entries that inserted incorrect imports.
 - **Duplicate `use function` insertion.** Accepting a function completion no longer inserts a `use function` statement when the exact import already exists in the file.

examples/laravel/.phpantom.toml

@@ -0,0 +1,3 @@
+[diagnostics]
+unresolved-member-access = true
+report-magic-properties = true

src/config.rs

@@ -67,6 +67,18 @@ pub struct DiagnosticsConfig {
     /// you want stricter checking.
     #[serde(rename = "extra-arguments")]
     pub extra_arguments: Option<bool>,
+
+    /// Report property access on classes with `__get` when virtual
+    /// properties are defined.
+    ///
+    /// Off by default. When enabled, classes that have `__get` but
+    /// also declare virtual properties (via `@property` docblock tags,
+    /// Laravel Eloquent column inference, or any other virtual member
+    /// provider) will flag unknown property access instead of
+    /// suppressing it. This matches PHPStan's `reportMagicProperties`
+    /// behaviour.
+    #[serde(rename = "report-magic-properties")]
+    pub report_magic_properties: Option<bool>,
 }
 
 impl DiagnosticsConfig {
@@ -83,6 +95,13 @@ impl DiagnosticsConfig {
     pub fn extra_arguments_enabled(&self) -> bool {
         self.extra_arguments.unwrap_or(false)
     }
+
+    /// Whether magic property reporting is enabled.
+    ///
+    /// Defaults to `false` (off) when not explicitly set.
+    pub fn report_magic_properties_enabled(&self) -> bool {
+        self.report_magic_properties.unwrap_or(false)
+    }
 }
 
 /// `[formatting]` section — controls the formatting strategy.
@@ -526,6 +545,7 @@ mod tests {
         assert!(config.php.version.is_none());
         assert!(!config.diagnostics.unresolved_member_access_enabled());
         assert!(!config.diagnostics.extra_arguments_enabled());
+        assert!(!config.diagnostics.report_magic_properties_enabled());
         assert_eq!(config.indexing.strategy(), IndexingStrategy::Composer);
         assert!(config.formatting.php_cs_fixer.is_none());
         assert!(config.formatting.phpcbf.is_none());
@@ -554,6 +574,7 @@ mod tests {
         assert!(config.php.version.is_none());
         assert!(!config.diagnostics.unresolved_member_access_enabled());
         assert!(!config.diagnostics.extra_arguments_enabled());
+        assert!(!config.diagnostics.report_magic_properties_enabled());
         assert_eq!(config.indexing.strategy(), IndexingStrategy::Composer);
         assert!(config.formatting.php_cs_fixer.is_none());
         assert!(config.formatting.phpcbf.is_none());
@@ -571,6 +592,7 @@ mod tests {
         assert!(config.php.version.is_none());
         assert!(!config.diagnostics.unresolved_member_access_enabled());
         assert!(!config.diagnostics.extra_arguments_enabled());
+        assert!(!config.diagnostics.report_magic_properties_enabled());
         assert_eq!(config.indexing.strategy(), IndexingStrategy::Composer);
         assert!(config.formatting.php_cs_fixer.is_none());
         assert!(config.formatting.phpcbf.is_none());
@@ -606,6 +628,24 @@ mod tests {
         assert!(!config.diagnostics.unresolved_member_access_enabled());
     }
 
+    #[test]
+    fn parses_report_magic_properties() {
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path().join(CONFIG_FILE_NAME);
+        std::fs::write(&path, "[diagnostics]\nreport-magic-properties = true\n").unwrap();
+        let config = load_config(dir.path()).unwrap();
+        assert!(config.diagnostics.report_magic_properties_enabled());
+    }
+
+    #[test]
+    fn report_magic_properties_defaults_to_false() {
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path().join(CONFIG_FILE_NAME);
+        std::fs::write(&path, "[diagnostics]\n").unwrap();
+        let config = load_config(dir.path()).unwrap();
+        assert!(!config.diagnostics.report_magic_properties_enabled());
+    }
+
     #[test]
     fn extra_arguments_defaults_to_false() {
         let dir = tempfile::tempdir().unwrap();
@@ -722,6 +762,7 @@ version = "8.2"
 [diagnostics]
 unresolved-member-access = true
 extra-arguments = true
+report-magic-properties = true
 
 [indexing]
 strategy = "self"
@@ -752,6 +793,7 @@ analyze-timeout = 45000
         assert_eq!(config.php.version.as_deref(), Some("8.2"));
         assert!(config.diagnostics.unresolved_member_access_enabled());
         assert!(config.diagnostics.extra_arguments_enabled());
+        assert!(config.diagnostics.report_magic_properties_enabled());
         assert_eq!(config.indexing.strategy, Some(IndexingStrategy::SelfScan));
         assert_eq!(config.formatting.php_cs_fixer.as_deref(), Some(""));
         assert_eq!(

src/diagnostics/unknown_members/mod.rs

@@ -656,6 +656,8 @@ impl Backend {
         end: u32,
     ) -> (MemberCheckResult, Vec<Diagnostic>) {
         let mut diagnostics = Vec::new();
+        let report_magic = self.config().diagnostics.report_magic_properties_enabled();
+
         // ── Quick check on pre-resolved base classes ────────────────
         // `resolve_target_classes` already returns fully-resolved
         // classes in many code paths (e.g. `type_hint_to_classes_typed`
@@ -675,7 +677,7 @@ impl Backend {
         if !is_method_call
             && base_classes
                 .iter()
-                .any(|c| has_magic_method_for_access(c, is_static, false))
+                .any(|c| has_magic_method_for_access(c, is_static, false, report_magic))
         {
             return (MemberCheckResult::Ok, diagnostics);
         }
@@ -709,7 +711,7 @@ impl Backend {
         if !is_method_call
             && resolved_classes
                 .iter()
-                .any(|c| has_magic_method_for_access(c, is_static, false))
+                .any(|c| has_magic_method_for_access(c, is_static, false, report_magic))
         {
             return (MemberCheckResult::Ok, diagnostics);
         }
@@ -737,10 +739,10 @@ impl Backend {
         let has_magic_call = is_method_call
             && (base_classes
                 .iter()
-                .any(|c| has_magic_method_for_access(c, is_static, true))
+                .any(|c| has_magic_method_for_access(c, is_static, true, report_magic))
                 || resolved_classes
                     .iter()
-                    .any(|c| has_magic_method_for_access(c, is_static, true)));
+                    .any(|c| has_magic_method_for_access(c, is_static, true, report_magic)));
 
         // ── SoapClient: suppress diagnostic entirely ────────────────
         // SoapClient is a SOAP proxy where any method name is valid
@@ -949,7 +951,18 @@ fn member_exists(
 /// Check whether the class has a magic method that would handle the
 /// member access at runtime, making the "unknown member" diagnostic
 /// a false positive.
-fn has_magic_method_for_access(class: &ClassInfo, is_static: bool, is_method_call: bool) -> bool {
+///
+/// For property access, `__get` only suppresses the diagnostic when
+/// the class has no `@property` annotations.  When `@property` tags
+/// exist, they define the expected property surface and unknown
+/// properties should be flagged (matching PHPStan's behaviour with
+/// `reportMagicProperties: true`).
+fn has_magic_method_for_access(
+    class: &ClassInfo,
+    is_static: bool,
+    is_method_call: bool,
+    report_magic_properties: bool,
+) -> bool {
     if is_method_call {
         let magic = if is_static { "__callStatic" } else { "__call" };
         return class
@@ -959,11 +972,24 @@ fn has_magic_method_for_access(class: &ClassInfo, is_static: bool, is_method_cal
     }
 
     if !is_static {
-        // Instance property access — `__get` handles arbitrary property names.
-        return class
+        // Instance property access — `__get` handles arbitrary property
+        // names.  When `report_magic_properties` is enabled and any
+        // virtual member provider has added properties to the class
+        // (@property docblock tags, Laravel Eloquent column inference,
+        // etc.), do not suppress — let normal member checking flag
+        // unknowns.  When disabled (the default), `__get` always
+        // suppresses.
+        let has_get = class
             .methods
             .iter()
             .any(|m| m.name.eq_ignore_ascii_case("__get"));
+        if has_get {
+            if report_magic_properties {
+                let has_virtual_properties = class.properties.iter().any(|p| p.is_virtual);
+                return !has_virtual_properties;
+            }
+            return true;
+        }
     }
 
     false