Filter stub constants by @removed version when setting PHP version

Author: AJenbo

docs/ARCHITECTURE.md

@@ -544,11 +544,12 @@ PHPantom detects the target PHP version during `initialized`:
 
 The detected version is stored on the `Backend` as a `PhpVersion(major, minor)`.
 
-When parsing stubs (both class stubs via `find_or_load_class` and function stubs via `find_or_load_function`), the PHP version is passed through `DocblockCtx.php_version` to the extraction functions. Three filtering points apply:
+When parsing stubs (both class stubs via `find_or_load_class` and function stubs via `find_or_load_function`), the PHP version is passed through `DocblockCtx.php_version` to the extraction functions. Four filtering points apply:
 
 - **Function-level:** `extract_functions_from_statements` checks the function's `#[PhpStormStubsElementAvailable]` attribute. If the version range excludes the target, the entire function is skipped. This handles duplicate function definitions (e.g. `array_combine` has separate signatures for PHP ≤7.4 and ≥8.0).
 - **Method-level:** `extract_class_like_members` applies the same check to methods. For example, `SplFixedArray::__serialize` (from PHP 8.2) is excluded when targeting PHP 8.1.
 - **Parameter-level:** `extract_parameters` filters individual parameters. For example, `array_map`'s untyped `$arrays` parameter (PHP 5.3–7.4) is excluded when targeting PHP 8.0+, leaving only the typed `array $array`.
+- **Constant-level:** `set_php_version` calls `is_stub_constant_removed` to evict constants whose `@removed X.Y` tag indicates they were removed at or before the target version (e.g. `MCRYPT_ENCRYPT` with `@removed 7.2`).
 
 The attribute supports named arguments (`from: '8.0'`, `to: '7.4'`) and a positional argument (`'8.1'` treated as `from`). Both bounds are inclusive. A missing bound means unbounded in that direction.
 

docs/CHANGELOG.md

@@ -59,6 +59,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **Version-gated stub constants now filtered.** Constants with `@removed` tags (e.g. `MCRYPT_ENCRYPT`, removed in PHP 7.2) are now excluded from completion and resolution when the project targets a newer PHP version. Previously only classes and functions were filtered.
 - **Go-to-definition.** Fixed a potential deadlock when navigating to a vendor class that hadn't been parsed yet.
 - **LSP no longer freezes under heavy editor activity.** Server-to-client requests (diagnostic refresh, progress token creation) could deadlock the service loop when the editor was simultaneously sending bursts of open/close/hover messages. All server-to-client requests are now either fire-and-forget or time-bounded, long-running handlers are cancellation-safe, and the process exits cleanly if the service loop ever terminates unexpectedly.
 - **Rename class preserves `self`, `static`, and `parent` keywords.** Renaming a class no longer replaces occurrences of `self::`, `static::`, or `parent::` with the new class name.

docs/todo/refactor.md

@@ -212,25 +212,7 @@ Each item must include:
 
 ---
 
-## Outstanding items
-
-### R3. Backward `@var` scanner in `docblock/tags.rs` 🟠
-
-`src/docblock/tags.rs` L520–620 (`find_var_raw_type_in_source`) and L1000–1100
-(`find_iterable_raw_type_in_source`) scan source lines backward with
-`lines().rev()`, manually tracking brace depth and sibling scopes via character
-counting. This reimplements scope analysis that the forward walker and
-`scope_collector/` already provide. Called from `call_resolution.rs` (L1251,
-L2793) and `array_shape.rs` (L519), making them load-bearing.
-
-**Action:** Replace with forward walker variable resolution or ensure the
-forward walker captures `@var` annotations so these backward scanners become
-unnecessary.
-
-**Files:** `src/docblock/tags.rs`, `src/completion/call_resolution.rs`,
-`src/completion/array_shape.rs`
-
----
+# Outstanding items
 
 ## Intentional overlap (reference, not actionable)
 
@@ -258,4 +240,90 @@ A minor inefficiency, not a parallel system.
 back to linear scan of `uri_classes_index`. Covers race conditions during initial
 indexing. Legitimate safety net.
 
+### `DIAGNOSTIC_SCOPE` vs `HOVER_SCOPE_CACHE`
+
+Two caches storing the same data type (`ScopeSnapshotMap`) for different consumers.
+`DIAGNOSTIC_SCOPE` is ephemeral/per-pass (build all scopes for the whole file,
+discard on drop). `HOVER_SCOPE_CACHE` is persistent/per-method with content-hash
+invalidation. The split is intentional: diagnostics check every line so they
+build all scopes upfront; hover checks one spot so it lazily caches per-method.
+However, the `is_diagnostic_scope_active()` guard causes ~14 behavioral forks
+in the forward walker, meaning bugs fixed for one consumer may not manifest for
+the other. Unifying them would eliminate the divergent walker behavior.
+
+### Consumer-gated caches
+
+`CALLABLE_TARGET_CACHE`, `PARSE_CACHE`, and `ACTIVE_RESOLVED_CACHE` are activated
+only during diagnostic/analyse passes. Completion and hover re-resolve callable
+targets and re-parse files from scratch. Extending these to all consumers would
+avoid redundant work.
+
+### `MIXIN_CACHE` never invalidated
+
+`src/virtual_members/phpdoc.rs` `MIXIN_CACHE` is a thread-local
+`HashMap<String, Arc<ClassInfo>>` that caches resolved mixin classes. It is used
+by all consumers (completion, hover, diagnostics) but is never cleared during
+normal LSP operation. If a mixin class definition changes (e.g. a method is added
+to `Illuminate\Database\Eloquent\Builder`), the cache serves stale data until the
+thread dies. Needs content-hash or generation-counter invalidation.
+
+---
+
+## Redundant backwards text walkers
+
+These functions in `src/completion/source/helpers.rs` scan backward with `rfind`
+to find the most recent assignment to a variable. The forward walker's scope map
+already tracks this information during its top-to-bottom pass.
+
+### `extract_closure_return_type_from_assignment`
+
+Uses `rfind("$fn = ")` backward from cursor, then parses closure return type
+from raw text. The forward walker already processes closure assignments and
+extracts return types from the AST node's type hint. Callers in
+`call_resolution.rs` (L1272) and `rhs_resolution.rs` (L2695) should read the
+variable's type from the scope map instead.
+
+### `extract_first_class_callable_return_type`
+
+Uses `rfind("$fn = ")` backward, then resolves `Foo::bar(...)` callable return
+type from text. The forward walker already handles first-class callable
+assignments. Callers in `call_resolution.rs` (L1292) and `rhs_resolution.rs`
+(L2718) should use the scope map.
+
+### `extract_function_return_from_source`
+
+Uses `rfind("/**")` backward to get `@return` type for functions not yet in
+`global_functions`. This is a fallback for unindexed functions and is harder to
+replace, but could be eliminated once all reachable functions are guaranteed to
+be indexed before resolution runs.
+
+---
+
+## SymbolMap data re-extracted from AST
+
+The SymbolMap is built once per file in `update_ast_inner` and stores symbol
+spans, variable definitions, scope boundaries, and call sites. Several features
+re-parse the AST to extract information the SymbolMap already has.
+
+### Variable definition lookup
+
+The SymbolMap has `var_defs` with `find_var_definition()`, but
+`definition/variable/mod.rs` ignores it and does its own full AST walk via
+`find_variable_definition_in_program()`. The SymbolMap's `var_defs` are used
+elsewhere (hover, forward walk) but the go-to-definition feature duplicates
+the work.
+
+### Variables-in-scope collection
+
+`collect_variables_in_scope` in `completion.rs` re-parses the AST to find all
+variables visible at the cursor. The SymbolMap's `var_defs` already has every
+variable definition site with scope boundaries; this could be a filtered query
+on `var_defs` instead of a full AST walk.
+
+### Scope boundary detection
 
+The SymbolMap stores `scopes` (function/closure boundaries) and provides
+`find_enclosing_scope()`. Yet several code action helpers and diagnostic modules
+manually walk the AST to find the enclosing function/method body (e.g.
+`build_scope_map` in extract variable, inline variable, undefined variable
+diagnostics).

src/completion/call_resolution.rs

@@ -762,6 +762,7 @@ impl Backend {
             resolved_class_cache: Some(&self.resolved_class_cache),
             function_loader: Some(&function_loader_cl),
             scope_var_resolver: None,
+            is_in_static_method: false,
         };
 
         let parsed = SubjectExpr::parse(expr);

src/completion/handler.rs

@@ -944,6 +944,7 @@ impl Backend {
                         resolved_class_cache: Some(&self.resolved_class_cache),
                         function_loader: Some(&function_loader),
                         scope_var_resolver: None,
+                        is_in_static_method: false,
                     };
                     let mut resolved = super::resolver::resolve_target_classes(
                         &target.subject,
@@ -976,6 +977,7 @@ impl Backend {
                                 resolved_class_cache: Some(&self.resolved_class_cache),
                                 function_loader: Some(&function_loader),
                                 scope_var_resolver: None,
+                                is_in_static_method: false,
                             };
                             resolved = super::resolver::resolve_target_classes(
                                 &target.subject,

src/completion/resolver.rs

@@ -179,6 +179,11 @@ pub(crate) struct ResolutionCtx<'a> {
     /// `resolve_variable_types` which would trigger a full method-body
     /// re-walk.
     pub scope_var_resolver: ScopeVarResolverFn<'a>,
+    /// Whether the cursor is inside a `static` method body.
+    /// When `true`, `$this` is not available and `SubjectExpr::This`
+    /// resolves to nothing.  Precomputed from the `SymbolMap` at the
+    /// call site to avoid re-parsing the AST.
+    pub is_in_static_method: bool,
 }
 
 /// Bundles the common parameters threaded through variable-type resolution.
@@ -243,6 +248,7 @@ impl<'a> VarResolutionCtx<'a> {
             function_loader: self.loaders.function_loader,
             resolved_class_cache: self.resolved_class_cache,
             scope_var_resolver: self.scope_var_resolver,
+            is_in_static_method: false,
         }
     }
 
@@ -449,25 +455,9 @@ fn resolve_target_classes_expr_inner_impl(
     match expr {
         // ── Keywords that always mean "current class" ────────────
         SubjectExpr::This => {
-            // `$this` is not available inside static methods.  Check the
-            // AST to see whether the cursor is inside a static method body
-            // and return nothing if so.
-            if current_class.is_some() {
-                let cursor = ctx.cursor_offset;
-                let content = ctx.content;
-                let in_static = crate::parser::with_parsed_program(
-                    content,
-                    "this_static_check",
-                    |program, _| {
-                        crate::util::is_offset_in_static_method_in_program(
-                            &program.statements,
-                            cursor,
-                        )
-                    },
-                );
-                if in_static {
-                    return vec![];
-                }
+            // `$this` is not available inside static methods.
+            if current_class.is_some() && ctx.is_in_static_method {
+                return vec![];
             }
 
             // Check for `@param-closure-this` override: when the cursor

src/definition/implementation.rs

@@ -478,7 +478,9 @@ impl Backend {
             resolved_class_cache: Some(&self.resolved_class_cache),
             function_loader: Some(&function_loader),
             scope_var_resolver: None,
+            is_in_static_method: false,
         };
+
         let candidates = ResolvedType::into_arced_classes(
             crate::completion::resolver::resolve_target_classes(&subject, access_kind, &rctx),
         );

src/definition/member/mod.rs

@@ -133,6 +133,7 @@ impl Backend {
             resolved_class_cache: Some(&self.resolved_class_cache),
             function_loader: Some(&function_loader),
             scope_var_resolver: None,
+            is_in_static_method: false,
         };
         let candidates = ResolvedType::into_arced_classes(
             crate::completion::resolver::resolve_target_classes(subject, access_kind, &rctx),

src/definition/type_definition.rs

@@ -47,17 +47,29 @@ impl Backend {
         let function_loader = self.function_loader(&ctx);
 
         let resolved_types: Vec<PhpType> = match &symbol.kind {
-            SymbolKind::Variable { name } => resolve_variable_type_names(
-                name,
-                content,
-                offset,
-                current_class,
-                &ctx,
-                &class_loader,
-                &function_loader,
-            )
-            .into_iter()
-            .collect(),
+            SymbolKind::Variable { name } => {
+                let in_static = self
+                    .symbol_maps
+                    .read()
+                    .get(uri)
+                    .is_some_and(|map| map.is_in_static_method(offset));
+                // $this is not available in static methods.
+                if name == "this" && in_static {
+                    Vec::new()
+                } else {
+                    resolve_variable_type_names(
+                        name,
+                        content,
+                        offset,
+                        current_class,
+                        &ctx,
+                        &class_loader,
+                        &function_loader,
+                    )
+                    .into_iter()
+                    .collect()
+                }
+            }
 
             SymbolKind::MemberAccess {
                 subject_text,
@@ -83,6 +95,7 @@ impl Backend {
                         &function_loader as &dyn Fn(&str) -> Option<FunctionInfo>,
                     ),
                     scope_var_resolver: None,
+                    is_in_static_method: false,
                 };
 
                 let candidates = ResolvedType::into_arced_classes(
@@ -276,18 +289,8 @@ fn resolve_variable_type_names(
     class_loader: &dyn Fn(&str) -> Option<Arc<ClassInfo>>,
     function_loader: &dyn Fn(&str) -> Option<FunctionInfo>,
 ) -> Option<PhpType> {
-    // $this resolves to the enclosing class, but not in static methods.
+    // $this resolves to the enclosing class.
     if name == "this" {
-        let in_static =
-            crate::parser::with_parsed_program(content, "this_static_typedef", |program, _| {
-                crate::util::is_offset_in_static_method_in_program(
-                    &program.statements,
-                    cursor_offset,
-                )
-            });
-        if in_static {
-            return None;
-        }
         return current_class.map(|cc| PhpType::Named(cc.name.to_string()));
     }
 

src/diagnostics/deprecated.rs

@@ -170,6 +170,7 @@ impl Backend {
                                     resolved_class_cache: Some(cache),
                                     function_loader: Some(&function_loader),
                                     scope_var_resolver: None,
+                                    is_in_static_method: false,
                                 };
 
                                 resolve_variable_subject(subject_text, *is_static, &rctx)