Improve PHP version awareness

Author: AJenbo

docs/ARCHITECTURE.md

@@ -352,6 +352,28 @@ Deduplication uses the map key (FQN), so two functions with the same short name
 
 The `stub_constant_index` (`HashMap<&'static str, &'static str>`) is built at construction time from `STUB_CONSTANT_MAP`, mapping constant names like `PHP_EOL`, `PHP_INT_MAX`, `SORT_ASC` to their stub file source. This infrastructure is in place for future use (e.g. constant value/type resolution, completion of standalone constants) but is not yet consulted by any resolution path.
 
+### Version-Aware Filtering
+
+phpstorm-stubs annotate functions, methods, and parameters with `#[PhpStormStubsElementAvailable]` attributes to indicate which PHP versions they apply to. For example, `array_map` has two variants of its second parameter: `array $array` (from PHP 8.0) and an untyped `$arrays` (PHP 5.3 to 7.4). Without filtering, both appear in signatures.
+
+PHPantom detects the target PHP version during `initialized`:
+
+1. Read `config.platform.php` from `composer.json` (explicit platform override).
+2. Fall back to `require.php` from `composer.json` (e.g. `"^8.4"` → 8.4).
+3. Default to PHP 8.5 when neither is available.
+
+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:
+
+- **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`.
+
+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.
+
+User code is never filtered. The `php_version` field in `DocblockCtx` is `None` for files parsed via `update_ast`, so the filtering logic is a no-op for non-stub code.
+
 ### Graceful Degradation
 
 If the stubs aren't installed (e.g. `composer install` hasn't been run), `build.rs` generates empty arrays and the build succeeds. The LSP just won't know about built-in PHP symbols.

docs/CHANGELOG.md

@@ -17,7 +17,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
-- **PHP version-aware stubs.** PHPantom detects the target PHP version from `composer.json` (`config.platform.php` or `require.php`) and filters built-in stub signatures accordingly. Functions, methods, and parameters annotated with `#[PhpStormStubsElementAvailable]` that do not apply to the detected version are excluded. For example, `array_map` on PHP 8.4 shows `array $array` instead of the untyped `$arrays` parameter from PHP 7.4. When no version is detected, PHP 8.5 is assumed.
+- **PHP version-aware stubs.** PHPantom detects the target PHP version from `composer.json` (`config.platform.php` or `require.php`) and filters built-in stub signatures accordingly. Functions, methods, and parameters annotated with `#[PhpStormStubsElementAvailable]` (including aliased forms used in some stub files) that do not apply to the detected version are excluded. For example, `array_map` on PHP 8.4 shows `array $array` instead of the untyped `$arrays` parameter from PHP 7.4. When no version is detected, PHP 8.5 is assumed.
 - **Docblock navigation.** Go-to-definition and hover now work on class names inside callable type annotations (`\Closure(Request): Response`), array and object shape value types (`array{logger: Pen, debug: bool}`), and Ctrl+Click on object shape properties (`$profile->name` from `@return object{name: string}`) jumps to the key inside the docblock.
 - **AST-based array type inference.** Array shape key completion and array element member access resolve through an AST walker that handles literal arrays, `new` expressions, call expressions, spread elements, incremental key assignments, and push-style assignments. Scalar values in array literals are inferred with precise types instead of `mixed`.
 - **Symbol map coverage expanded.** Anonymous classes, top-level `const` declarations, language constructs (`isset`, `empty`, `print`, etc.), string interpolation expressions, first-class callable syntax (`strlen(...)`, `Foo::bar(...)`), standalone constant references, `declare` bodies, short echo tags, array append expressions, and pipe operator expressions now produce navigable symbol spans.

docs/todo.md

@@ -633,13 +633,122 @@ These functions have return type semantics that don't fit into either
 
 ---
 
+### 18. `LanguageLevelTypeAware` version-aware type hints
+**Impact: Medium · Effort: Medium**
+
+phpstorm-stubs use a second version attribute, `#[LanguageLevelTypeAware]`,
+to override **type hints** (not element availability) based on the PHP
+version. Unlike `#[PhpStormStubsElementAvailable]` which controls whether
+an entire function, method, or parameter exists, `LanguageLevelTypeAware`
+changes the type of a parameter or return value while the element itself
+stays present. There are ~2,000 occurrences across the stubs.
+
+The attribute takes an associative array mapping version strings to type
+hints, plus a `default` fallback:
+
+```php
+// Return type changes by version:
+#[LanguageLevelTypeAware(["8.4" => "StreamBucket|null"], default: "object|null")]
+function stream_bucket_make_writeable($brigade) {}
+
+// Parameter type changes by version:
+function array_key_exists(
+    $key,
+    #[LanguageLevelTypeAware(["8.0" => "array"], default: "array|ArrayObject")] $array
+): bool {}
+```
+
+PHPantom currently ignores these attributes. The native type hint from the
+AST is used as-is, which means on PHP 8.4 a function might show
+`object|null` instead of `StreamBucket|null`, or a parameter might show
+`array|ArrayObject` instead of `array`.
+
+**Implementation:** During parameter and return-type extraction (when
+`DocblockCtx.php_version` is set), scan the element's attributes for
+`LanguageLevelTypeAware`. Find the highest version key that is ≤ the
+target version. If found, use that type string as the native type hint;
+otherwise use the `default` value. This should integrate into the same
+extraction points that already handle `PhpStormStubsElementAvailable`.
+
+**Note:** Two stub files alias the attribute name: `intl/intl.php` uses
+`LanguageAware` (~249 usages) and `ldap/ldap.php` uses `PhpVersionAware`
+(~101 usages). The attribute matcher must recognise all three names.
+
+---
+
+### 19. `#[ArrayShape]` return shapes on stub functions
+**Impact: Medium · Effort: Medium**
+
+phpstorm-stubs annotate ~84 functions and methods with
+`#[ArrayShape(["key" => "type", ...])]` to declare the structure of
+their array return values. Almost none of these have a companion
+`@return array{...}` docblock, so the shape information is invisible
+to PHPantom. This affects commonly used functions like `parse_url`,
+`stat`, `pathinfo`, `gc_status`, `getimagesize`,
+`session_get_cookie_params`, `stream_get_meta_data`, and
+`password_get_info`.
+
+```php
+#[ArrayShape(["lifetime" => "int", "path" => "string", "domain" => "string",
+              "secure" => "bool", "httponly" => "bool", "samesite" => "string"])]
+function session_get_cookie_params(): array {}
+
+#[ArrayShape(["runs" => "int", "collected" => "int", "threshold" => "int", "roots" => "int"])]
+function gc_status(): array {}
+```
+
+**Implementation:** During function/method extraction, scan for the
+`ArrayShape` attribute. Parse the associative array literal in its
+argument to build an `array{key: type, ...}` string, and use it as
+the effective return type (or parameter type when applied to a
+parameter). This complements the existing docblock `array{...}`
+parsing and should feed into the same `return_type` field on
+`FunctionInfo` / `MethodInfo`.
+
+---
+
 <!-- ============================================================ -->
 <!--  TIER 4 — LOW-MEDIUM IMPACT                                  -->
 <!-- ============================================================ -->
 
 ## Low-Medium Impact
 
-### 18. Asymmetric visibility (PHP 8.4)
+### 20. `#[Deprecated]` structured deprecation metadata
+**Impact: Low-Medium · Effort: Low**
+
+phpstorm-stubs annotate ~362 functions, methods, classes, constants,
+properties, and parameters with `#[Deprecated(reason: "...",
+replacement: "...", since: "X.Y")]`. PHPantom already reads
+`@deprecated` from docblocks, but many stub entries use the attribute
+instead of (or in addition to) a docblock tag. The attribute carries
+richer data than the free-text `@deprecated` tag:
+
+- `since` — the PHP version when the element was deprecated. Combined
+  with PHP version detection, this could suppress deprecation warnings
+  when targeting an older version where the element was not yet
+  deprecated, or show "deprecated since PHP 8.0" in hover.
+- `reason` — a human-readable explanation.
+- `replacement` — a code template for auto-replacement (e.g.
+  `"exif_read_data(%parametersList%)"` for `read_exif_data`). Could
+  power a future "replace deprecated call" code action.
+
+```php
+#[Deprecated(reason: "Use anonymous functions instead", since: "7.2")]
+function create_function(string $args, string $code): false|string {}
+
+#[Deprecated(replacement: "exif_read_data(%parametersList%)", since: "7.2")]
+function read_exif_data($filename, $sections = null, $arrays = false, $thumbnail = false) {}
+```
+
+**Implementation:** During extraction, scan for the `Deprecated`
+attribute. Store the `since`, `reason`, and `replacement` fields on
+`FunctionInfo` / `MethodInfo` / `ClassInfo`. In hover, prefer the
+structured message over the raw `@deprecated` text. Optionally, use
+the `since` version to make deprecation warnings version-aware.
+
+---
+
+### 21. Asymmetric visibility (PHP 8.4)
 **Impact: Low-Medium · Effort: Low**
 
 Separate from property hooks, PHP 8.4 allows asymmetric visibility on
@@ -669,7 +778,7 @@ is just to store the value; context-aware filtering can follow later.
 
 ---
 
-### 19. `str_contains` / `str_starts_with` / `str_ends_with` → non-empty-string narrowing
+### 22. `str_contains` / `str_starts_with` / `str_ends_with` → non-empty-string narrowing
 **Impact: Low-Medium · Effort: Low**
 
 When `str_contains($haystack, $needle)` appears in a condition and
@@ -686,7 +795,7 @@ See `StrContainingTypeSpecifyingExtension` in PHPStan.
 
 ---
 
-### 20. `count` / `sizeof` comparison → non-empty-array narrowing
+### 23. `count` / `sizeof` comparison → non-empty-array narrowing
 **Impact: Low-Medium · Effort: Low**
 
 `if (count($arr) > 0)` or `if (count($arr) >= 1)` narrows `$arr` to
@@ -698,7 +807,7 @@ branches in `TypeSpecifier::specifyTypesInCondition`.
 
 ---
 
-### 21. Go-to-definition for array shape keys via bracket access
+### 24. Go-to-definition for array shape keys via bracket access
 **Impact: Low · Effort: Medium**
 
 Array shape keys accessed via bracket notation (`$status['code']`)
@@ -723,7 +832,7 @@ key inside the matching `array{…}` annotation.
 
 ## Low Impact
 
-### 22. Short-name collisions in `find_implementors`
+### 25. Short-name collisions in `find_implementors`
 **Impact: Low · Effort: Low**
 
 `class_implements_or_extends` matches interfaces by both short name and
@@ -739,7 +848,7 @@ before comparison.
 
 ---
 
-### 23. Fiber type resolution
+### 26. Fiber type resolution
 **Impact: Low · Effort: Low**
 
 `Generator<TKey, TValue, TSend, TReturn>` has dedicated support for
@@ -754,7 +863,7 @@ Generator extraction in `docblock/types.rs`.
 
 ---
 
-### 24. Non-empty-string propagation through string functions
+### 27. Non-empty-string propagation through string functions
 **Impact: Low · Effort: Low**
 
 PHPStan tracks `non-empty-string` through string-manipulating
@@ -772,7 +881,7 @@ See `NonEmptyStringFunctionsReturnTypeExtension` in PHPStan.
 
 ---
 
-### 25. `Closure::bind()` / `Closure::fromCallable()` return type preservation
+### 28. `Closure::bind()` / `Closure::fromCallable()` return type preservation
 **Impact: Low · Effort: Low-Medium**
 
 Variables holding closure literals, arrow functions, and first-class
@@ -788,7 +897,7 @@ See `ClosureBindDynamicReturnTypeExtension` and
 
 ---
 
-### 26. Non-array functions with dynamic return types
+### 29. Non-array functions with dynamic return types
 **Impact: Low · Effort: High**
 
 PHPStan also provides dynamic return type extensions for many non-array
@@ -819,7 +928,7 @@ return types (less impactful for class-based completion).
 
 ---
 
-### 27. Language construct signature help and hover
+### 30. Language construct signature help and hover
 **Impact: Low · Effort: Low**
 
 PHP language constructs that use parentheses (`unset()`, `isset()`, `empty()`,
@@ -836,22 +945,100 @@ need a similar hardcoded lookup.
 
 ---
 
-### 28. Diagnostics
+### 31. `#[ReturnTypeContract]` parameter-dependent return types
+**Impact: Low · Effort: Low**
+
+phpstorm-stubs use `#[ReturnTypeContract]` (aliased as `TypeContract`)
+on 4 functions to express return type narrowing based on a parameter's
+value or presence. These functions have no `@phpstan-return` conditional
+type in their docblocks, so the narrowing information is only available
+through the attribute.
+
+The attribute has four named arguments:
+- `true` / `false` — narrows the return type when the annotated boolean
+  parameter is `true` or `false`.
+- `exists` / `notExists` — narrows the return type when an optional
+  variadic parameter is passed or omitted.
+
+```php
+// microtime(true) → float, microtime(false) → string
+function microtime(
+    #[TypeContract(true: "float", false: "string")] bool $as_float = false
+): string|float {}
+
+// sscanf with extra args → int|null, without → array|null
+function sscanf(
+    string $string, string $format,
+    #[TypeContract(exists: "int|null", notExists: "array|null")] mixed &...$vars
+): array|int|null {}
+```
+
+Affected functions: `microtime`, `gettimeofday`, `sscanf`, `fscanf`.
+
+**Implementation:** When resolving a call to one of these functions,
+check whether the annotated parameter was passed (for `exists`/
+`notExists`) or matches a literal boolean (for `true`/`false`). Use the
+narrowed type from the attribute instead of the declared union return
+type. This integrates into the call return type resolution path.
+
+---
+
+### 32. `#[ExpectedValues]` parameter value suggestions
+**Impact: Low · Effort: Medium**
+
+phpstorm-stubs annotate ~62 parameters and return values (including
+usages via the `EV` alias in `intl` and `ftp`) with
+`#[ExpectedValues]` to declare the set of valid constant values or
+flags. This could power smarter completions inside function call
+arguments by suggesting the valid constants.
+
+The attribute supports several forms:
+- `values: [CONST_A, CONST_B]` — one of the listed values is expected.
+- `flags: [FLAG_A, FLAG_B]` — a bitmask combination is expected.
+- `valuesFromClass: MyClass::class` — one of the class's constants.
+- `flagsFromClass: MyClass::class` — bitmask of the class's constants.
+
+```php
+function phpinfo(
+    #[ExpectedValues(flags: [INFO_GENERAL, INFO_CREDITS, INFO_CONFIGURATION,
+                             INFO_MODULES, INFO_ENVIRONMENT, INFO_VARIABLES,
+                             INFO_LICENSE, INFO_ALL])]
+    int $flags = INFO_ALL
+): bool {}
+
+function pathinfo(
+    string $path,
+    #[ExpectedValues(flags: [PATHINFO_DIRNAME, PATHINFO_BASENAME,
+                             PATHINFO_EXTENSION, PATHINFO_FILENAME])]
+    int $flags = PATHINFO_ALL
+): string|array {}
+```
+
+**Implementation:** During parameter extraction, store the expected
+values metadata. When providing completions inside a function call
+argument position, check whether the target parameter has expected
+values and offer the listed constants at the top of the suggestions
+list. Flag-style parameters should also suggest bitwise-OR
+combinations.
+
+---
+
+### 33. Diagnostics
 **Impact: Low (large scope) · Effort: Very High**
 
 No error reporting (undefined methods, type mismatches, etc.).
 
 ---
 
-### 29. Code Actions
+### 34. Code Actions
 **Impact: Low · Effort: Very High**
 
 No quick fixes or refactoring suggestions. No `codeActionProvider` in
 `ServerCapabilities`, no `textDocument/codeAction` handler, and no
 `WorkspaceEdit` generation infrastructure beyond trivial `TextEdit`s for
 use-statement insertion.
 
-#### 29a. Extract Function refactoring
+#### 34a. Extract Function refactoring
 
 Select a range of statements inside a method/function and extract them into a
 new function. The LSP would need to:

src/parser/ast_update.rs

@@ -54,6 +54,7 @@ impl Backend {
             trivias: program.trivia.as_slice(),
             content,
             php_version: None,
+            use_map: HashMap::new(),
         };
 
         // Extract all three in a single parse pass.

src/parser/classes.rs

@@ -1453,7 +1453,7 @@ impl Backend {
                     // range excludes the target PHP version.
                     if let Some(ctx) = doc_ctx
                         && let Some(ver) = ctx.php_version
-                        && !is_available_for_version(&method.attribute_lists, ctx.content, ver)
+                        && !is_available_for_version(&method.attribute_lists, ctx, ver)
                     {
                         continue;
                     }
@@ -1465,6 +1465,7 @@ impl Backend {
                         &method.parameter_list,
                         doc_ctx.map(|ctx| ctx.content),
                         php_version,
+                        doc_ctx,
                     );
                     let native_return_type = method
                         .return_type_hint

src/parser/functions.rs

@@ -31,7 +31,7 @@ impl Backend {
                     // range excludes the target PHP version.
                     if let Some(ctx) = doc_ctx
                         && let Some(ver) = ctx.php_version
-                        && !is_available_for_version(&func.attribute_lists, ctx.content, ver)
+                        && !is_available_for_version(&func.attribute_lists, ctx, ver)
                     {
                         continue;
                     }
@@ -43,6 +43,7 @@ impl Backend {
                         &func.parameter_list,
                         doc_ctx.map(|ctx| ctx.content),
                         php_version,
+                        doc_ctx,
                     );
                     let native_return_type = func
                         .return_type_hint