Skip to content

Commit 843d8c7

Browse files
AJenboAJenbo
committed
Update roadmap
1 parent 32fb4b9 commit 843d8c7

4 files changed

Lines changed: 22 additions & 72 deletions

File tree

‎docs/todo.md‎

Lines changed: 10 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -65,8 +65,7 @@ within the same impact tier.
6565
| # | Item | Impact | Effort |
6666
| --- | -------------------------------------------------------------------------------------------------------------------------- | ----------- | ------ |
6767
| | Clear [refactoring gate](todo/refactor.md) | — | — |
68-
| C2 | [`LanguageLevelTypeAware` version-aware type hints](todo/completion.md#c2-languageleveltypeaware-version-aware-type-hints) | Medium-High | Medium |
69-
| C3 | [`#[ArrayShape]` return shapes on stub functions](todo/completion.md#c3-arrayshape-return-shapes-on-stub-functions) | Medium | Medium |
68+
| C2 | [`#[ArrayShape]` return shapes on stub functions](todo/completion.md#c2-arrayshape-return-shapes-on-stub-functions) | Medium | Medium |
7069
| T1 | [First-class callable resolution](todo/type-inference.md#t1-first-class-callables) | Medium | Medium |
7170
| T2 | [`@phpstan-type` / `@psalm-type` local type aliases](todo/type-inference.md#t2-local-type-aliases) | Medium | Medium |
7271
| T3 | [`@phpstan-import-type` cross-file type imports](todo/type-inference.md#t3-cross-file-type-imports) | Medium | Medium |
@@ -102,15 +101,15 @@ unlikely to move the needle for most users.
102101
| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------- | ----------- |
103102
| | **[Completion](todo/completion.md)** | | |
104103
| C1 | Array functions needing new code paths | Medium | High |
105-
| C10 | [Lazy documentation via `completionItem/resolve`](todo/completion.md#c10-lazy-documentation-via-completionitemresolve) | Medium | Medium |
106-
| C12 | [Smarter member ordering after `->` / `::`](todo/completion.md#c12-smarter-member-ordering-after----) | Medium | Medium |
107-
| C4 | Go-to-definition for array shape keys via bracket access | Low-Medium | Medium |
108-
| C8 | `class_alias()` support | Low-Medium | Medium |
109-
| C9 | [Filesystem proximity as an affinity tiebreaker](todo/completion.md#c9-filesystem-proximity-as-an-affinity-tiebreaker) | Low-Medium | Low |
110-
| C5 | Non-array functions with dynamic return types | Low | High |
111-
| C6 | `#[ReturnTypeContract]` parameter-dependent return types | Low | Low |
112-
| C7 | `#[ExpectedValues]` parameter value suggestions | Low | Medium |
113-
| C11 | [Deprecation markers on class-name completions from all sources](todo/completion.md#c11-deprecation-markers-on-class-name-completions-from-all-sources) | Low | Low |
104+
| C9 | [Lazy documentation via `completionItem/resolve`](todo/completion.md#c9-lazy-documentation-via-completionitemresolve) | Medium | Medium |
105+
| C11 | [Smarter member ordering after `->` / `::`](todo/completion.md#c11-smarter-member-ordering-after----) | Medium | Medium |
106+
| C3 | Go-to-definition for array shape keys via bracket access | Low-Medium | Medium |
107+
| C7 | `class_alias()` support | Low-Medium | Medium |
108+
| C8 | [Filesystem proximity as an affinity tiebreaker](todo/completion.md#c8-filesystem-proximity-as-an-affinity-tiebreaker) | Low-Medium | Low |
109+
| C4 | Non-array functions with dynamic return types | Low | High |
110+
| C5 | `#[ReturnTypeContract]` parameter-dependent return types | Low | Low |
111+
| C6 | `#[ExpectedValues]` parameter value suggestions | Low | Medium |
112+
| C10 | [Deprecation markers on class-name completions from all sources](todo/completion.md#c10-deprecation-markers-on-class-name-completions-from-all-sources) | Low | Low |
114113
| | **[Type Inference](todo/type-inference.md)** | | |
115114
| T7 | [`key-of<T>` and `value-of<T>` resolution](todo/type-inference.md#t7-key-oft-and-value-oft-resolution) | Medium | Medium |
116115
| T6 | `Closure::bind()` / `Closure::fromCallable()` return type preservation | Low-Medium | Low-Medium |

‎docs/todo/completion.md‎

Lines changed: 10 additions & 58 deletions
Original file line numberDiff line numberDiff line change
@@ -48,55 +48,7 @@ These functions have return type semantics that don't fit into either
4848

4949
---
5050

51-
## C2. `LanguageLevelTypeAware` version-aware type hints
52-
53-
**Impact: Medium · Effort: Medium**
54-
55-
phpstorm-stubs use a second version attribute, `#[LanguageLevelTypeAware]`,
56-
to override **type hints** (not element availability) based on the PHP
57-
version. Unlike `#[PhpStormStubsElementAvailable]` which controls whether
58-
an entire function, method, or parameter exists, `LanguageLevelTypeAware`
59-
changes the type of a parameter or return value while the element itself
60-
stays present. There are ~2,000 occurrences across the stubs.
61-
62-
The attribute takes an associative array mapping version strings to type
63-
hints, plus a `default` fallback:
64-
65-
```php
66-
// Return type changes by version:
67-
#[LanguageLevelTypeAware(["8.4" => "StreamBucket|null"], default: "object|null")]
68-
function stream_bucket_make_writeable($brigade) {}
69-
70-
// Parameter type changes by version:
71-
function array_key_exists(
72-
$key,
73-
#[LanguageLevelTypeAware(["8.0" => "array"], default: "array|ArrayObject")] $array
74-
): bool {}
75-
```
76-
77-
PHPantom currently ignores these attributes. The native type hint from the
78-
AST is used as-is, which means on PHP 8.4 a function might show
79-
`object|null` instead of `StreamBucket|null`, or a parameter might show
80-
`array|ArrayObject` instead of `array`.
81-
82-
**Implementation:** During parameter and return-type extraction (when
83-
`DocblockCtx.php_version` is set), scan the element's attributes for
84-
`LanguageLevelTypeAware`. Find the highest version key that is ≤ the
85-
target version. If found, use that type string as the native type hint;
86-
otherwise use the `default` value. This should integrate into the same
87-
extraction points that already handle `PhpStormStubsElementAvailable`.
88-
89-
**Attribute FQN:** `JetBrains\PhpStorm\Internal\LanguageLevelTypeAware`.
90-
Stub files import it via `use` statements, sometimes with aliases:
91-
`LanguageAware` (~249 usages in `intl/intl.php`) and `PhpVersionAware`
92-
(~101 usages in `ldap/ldap.php`). The attribute matcher must resolve
93-
through the `DocblockCtx` use-map (like `PhpStormStubsElementAvailable`
94-
and `Deprecated` already do) and compare the last segment of the resolved
95-
FQN, so all three names work automatically.
96-
97-
---
98-
99-
## C3. `#[ArrayShape]` return shapes on stub functions
51+
## C2. `#[ArrayShape]` return shapes on stub functions
10052

10153
**Impact: Medium · Effort: Medium**
10254

@@ -134,7 +86,7 @@ parsing and should feed into the same `return_type` field on
13486

13587
---
13688

137-
## C4. Go-to-definition for array shape keys via bracket access
89+
## C3. Go-to-definition for array shape keys via bracket access
13890

13991
**Impact: Low-Medium · Effort: Medium**
14092

@@ -154,7 +106,7 @@ key inside the matching `array{…}` annotation.
154106

155107
---
156108

157-
## C5. Non-array functions with dynamic return types
109+
## C4. Non-array functions with dynamic return types
158110

159111
**Impact: Low · Effort: High**
160112

@@ -186,7 +138,7 @@ return types (less impactful for class-based completion).
186138

187139
---
188140

189-
## C6. `#[ReturnTypeContract]` parameter-dependent return types
141+
## C5. `#[ReturnTypeContract]` parameter-dependent return types
190142

191143
**Impact: Low · Effort: Low**
192144

@@ -231,7 +183,7 @@ type. This integrates into the call return type resolution path.
231183

232184
---
233185

234-
## C7. `#[ExpectedValues]` parameter value suggestions
186+
## C6. `#[ExpectedValues]` parameter value suggestions
235187

236188
**Impact: Low · Effort: Medium**
237189

@@ -278,7 +230,7 @@ combinations.
278230

279231
---
280232

281-
## C8. `class_alias()` support
233+
## C7. `class_alias()` support
282234

283235
**Impact: Low-Medium · Effort: Medium**
284236

@@ -320,7 +272,7 @@ and no go-to-definition because PHPantom has no record of the alias.
320272

321273
---
322274

323-
## C9. Filesystem proximity as an affinity tiebreaker
275+
## C8. Filesystem proximity as an affinity tiebreaker
324276

325277
**Impact: Low-Medium · Effort: Low**
326278

@@ -354,7 +306,7 @@ candidate file.
354306
3. **Pass the current file path** through `ClassCompletionParams` and
355307
into `ClassItemCtx` so it's available during sort-text construction.
356308

357-
## C10. Lazy documentation via `completionItem/resolve`
309+
## C9. Lazy documentation via `completionItem/resolve`
358310

359311
**Impact: Medium · Effort: Medium**
360312

@@ -388,7 +340,7 @@ improves perceived latency on keystroke.
388340
optionally `detail`) eagerly in `build_item` and
389341
`build_completion_items`. Set `data` instead.
390342

391-
## C11. Deprecation markers on class-name completions from all sources
343+
## C10. Deprecation markers on class-name completions from all sources
392344

393345
**Impact: Low · Effort: Low**
394346

@@ -408,7 +360,7 @@ This is a small quality-of-life improvement: deprecated classes would
408360
show with a strikethrough in the completion menu across all sources,
409361
not just same-namespace ones.
410362

411-
## C12. Smarter member ordering after `->` / `::`
363+
## C11. Smarter member ordering after `->` / `::`
412364

413365
**Impact: Medium · Effort: needs planning**
414366

‎docs/todo/mago.md‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -677,8 +677,7 @@ significantly easier:
677677
| T7 (`key-of<T>` / `value-of<T>`) | `PhpType::KeyOf` and `PhpType::ValueOf` are first-class variants — just add resolution logic. |
678678
| T2 (`@phpstan-type` aliases) | Type aliases map a name to a `PhpType`. Substitution is a tree transform. |
679679
| T3 (`@phpstan-import-type`) | Same — cross-file alias resolution becomes FQN lookup + `PhpType` storage. |
680-
| C2 (version-aware type hints) | Replace `PhpType` nodes instead of patching type strings. |
681-
| C3 (`#[ArrayShape]` return shapes) | Build a `PhpType::Shape` directly from attribute data. |
680+
| C2 (`#[ArrayShape]` return shapes) | Build a `PhpType::Shape` directly from attribute data. |
682681
| L1 (Facade completion) | Preserve full `PhpType` from the concrete class instead of flattening to `@method static` strings. |
683682
| L4 (Custom Eloquent builders) | Resolve `HasBuilder<X>` as `PhpType::Reference { generic_args: [X] }` and extract X structurally. |
684683
| BL1 (Blade support) | Blade variable types (`$loop` as `object{index: int, ...}`) are `PhpType::Shape` values, not hand-built strings. |

‎docs/todo/phpactor-test-parity.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -371,7 +371,7 @@ initial value argument.
371371

372372
**phpactor ref:** `function/array_sum.test`
373373

374-
**Related todo:** [C5](completion.md#c5-non-array-functions-with-dynamic-return-types)
374+
**Related todo:** [C4](completion.md#c4-non-array-functions-with-dynamic-return-types)
375375

376376
**Effort: Medium** — requires function-specific return type logic.
377377

0 commit comments

Comments
 (0)