todo.md

PHPantom — Roadmap

This is the master index for all planned work. Each row links to the domain document that contains the full specification. Items are sequenced by sprint priority — what to build next to widen the type intelligence lead, then close the LSP feature gap, maximising coverage with each step.

Label	Scale
Impact	Critical, High, Medium-High, Medium, Low-Medium, Low
Effort	Low (≤ 1 day), Medium (2-5 days), Medium-High (1-2 weeks), High (2-4 weeks), Very High (> 1 month)

Domain Documents

Document	Scope
Type Inference	Generic resolution, conditional return types, type narrowing, stub attribute handling
Completion	Completion-specific improvements (enum return types, array shapes, expected values)
Diagnostics	Scalar member access errors, chain/return member diagnostics, unknown function errors, duplicate suppression, chain error propagation, deprecated rendering, unresolved PHPDoc types, suppression intelligence, composer warnings, argument count, unreachable code, implementation errors
Code Actions	Import class, remove unused imports, implement missing methods, null coalescing simplification, extract function, extract constant, inline variable, extract variable, inline function/method, switch→match, update docblock, change visibility, generate interface
LSP Features	Find references, document highlighting, document/workspace symbols, rename, code lens, inlay hints, PHPDoc generation, partial result streaming, formatting proxy, file rename on class rename
Signature Help	Parameter descriptions, signature-level docs, default values, attribute/closure support
Laravel	Model property gaps, relationship methods, type narrowing, custom builders
Blade	Preprocessor, component support, cross-file view intelligence
Bug Fixes	Incorrect behaviour that should be fixed regardless of feature priority
Configuration	Per-project .phpantom.toml file, PHP version override, diagnostic tool toggles, prompt-and-remember settings, stub extension selection, formatting tool selection
Refactoring	Technical debt and cleanup tasks. Gate check between sprints: clear all items before starting the next sprint
Indexing	Self-generated classmap, staleness detection, parallel file processing, full background indexing, disk cache
External Stubs	Composer stub discovery, IDE-provided stub paths, GTD for built-in symbols, stub override priority, SPL overlay stubs
Performance	FQN index, Arc<ClassInfo>, RwLock, inheritance dedup, file content cloning, type substitution optimisation
Inline Completion	Template engine (type-aware foreach/return/try-catch/match), n-gram prediction from PHP corpus, optional fine-tuned GGUF sidecar model

---

Sprint 3 — Quick wins: close the visible gaps

Every item here directly removes something a Neovim/Zed/VS Code user would notice as missing on day one. The remaining items round out the feature matrix with minimal risk.

The deferred performance items from Sprint 2.5 are included here because they are prerequisites for keeping everything fast as the feature surface grows.

#	Item	Effort	Domain	Doc Link
87	Reference-counted ClassInfo (Arc<ClassInfo>) — propagate through APIs	Medium	Performance	performance.md §2
94	Pull diagnostics (textDocument/diagnostic) — replace push model	Medium	Performance	performance.md §15
102	Implementation error diagnostic	Medium	Diagnostics	diagnostics.md §9
115	Syntax error diagnostic (surface Mago parse errors)	Low	Diagnostics	diagnostics.md §11

After Sprint 3: PHPantom feels like a complete LSP to everyday users. Outline, breadcrumbs, workspace search, semantic highlighting, folding, formatting, inlay hints, type hierarchy, document links, and smart select all work. No one says "it's missing X" for basic editing workflows.

---

Sprint 4 — Refactoring toolkit

Extract Function is the #1 personal feature request and something that was available before the switch to PHPantom. Inline Variable, Extract Variable, and Inline Function/Method have been specifically requested by the Neovim tester. These share scope analysis infrastructure with Extract Function, so building them together is the most efficient path.

#	Item	Effort	Domain	Doc Link
—	Clear refactoring gate	—	Refactoring	refactor.md
17	Extract Function refactoring	Very High	Code Actions	actions.md §3
76	Inline Variable	Medium	Code Actions	actions.md §7
77	Extract Variable	Medium	Code Actions	actions.md §8
78	Inline Function/Method	High	Code Actions	actions.md §9
109	Extract Constant	Medium	Code Actions	actions.md §10

After Sprint 4: The core refactoring toolkit is complete. The two most active testers have the features they specifically asked for. Scope analysis infrastructure built here benefits future code actions.

---

Sprint 5 — Polish for office adoption

These items close the gaps that PHPStorm and VS Code + Intelephense users at the office would notice. PHPDoc generation is the most common "where did that go?" moment. The implementation error diagnostic reuses existing code action logic and pairs with the quick-fix. File rename on class rename removes a friction point that Intelephense premium users expect.

#	Item	Effort	Domain	Doc Link
—	Clear refactoring gate	—	Refactoring	refactor.md
24	PHPDoc block generation on /**	Medium	LSP Features	lsp-features.md §3
114	Undefined variable diagnostic	Medium	Diagnostics	diagnostics.md §10
99	File rename on class rename	Medium	LSP Features	lsp-features.md §20
103	Stub extension selection ([stubs] extensions)	Low	Configuration	config.md §stubs

After Sprint 5: PHPantom is ready for office colleagues. They get PHPDoc generation, undefined variable detection, and the diagnostics they're used to. Nobody switching from Intelephense (free or premium) feels like they lost more than they gained.

---

Sprint 6 — Type intelligence depth

Type intelligence depth is PHPantom's defining advantage. This sprint deepens that lead with features that benefit the PHPStan enthusiast and Laravel developer alike. File system watching eliminates the "restart the server after composer update" friction.

#	Item	Effort	Domain	Doc Link
—	Clear refactoring gate	—	Refactoring	refactor.md
26	Inherited docblock type propagation	Medium	Type Inference	type-inference.md §4
27	BackedEnum::from() / ::tryFrom() return type refinement	Low	Completion	completion.md §1
28	Pipe operator (PHP 8.5) type resolution	Low	Type Inference	type-inference.md §1
29	Conditional return types ($param is T ? A : B)	Medium	Type Inference	type-inference.md §3
31	key-of<T> and value-of<T> resolution	Medium	Type Inference	type-inference.md §16
37	File system watching for vendor and project changes	Medium	Type Inference	type-inference.md §5
38	Property hooks (PHP 8.4)	Medium	Type Inference	type-inference.md §6
35	Resolution-failure diagnostics (unresolved function, unresolved PHPDoc type)	Medium	Diagnostics	diagnostics.md §3, §7
91	GTD for built-in symbols via project-level phpstorm-stubs	Low	External Stubs	external-stubs.md §1

After Sprint 6: PHPantom has the deepest type intelligence of any PHP language server. Conditional return types, key-of/value-of, property hooks, and inherited docblock types all work. The type engine advantage is unambiguous.

---

Sprint 7 — Remaining LSP features & code actions

Low-effort LSP features that didn't fit earlier sprints, plus code action polish.

#	Item	Effort	Domain	Doc Link
—	Clear refactoring gate	—	Refactoring	refactor.md
39	Simplify with null coalescing / null-safe operator (code action)	Medium	Code Actions	actions.md §2
110	Update docblock to match signature	Medium	Code Actions	actions.md §11
111	Change visibility	Low	Code Actions	actions.md §12

---

Sprint 8 — Deep type accuracy & Laravel excellence

These items push type resolution accuracy beyond what any tool offers. They're the long tail that makes PHPantom the definitive choice for projects that care about types.

#	Item	Effort	Domain	Doc Link
—	Clear refactoring gate	—	Refactoring	refactor.md
44	Custom Eloquent builders (HasBuilder / #[UseEloquentBuilder])	Medium	Laravel	laravel.md §3
45	abort_if/abort_unless type narrowing	Medium	Laravel	laravel.md §4
46	Narrow types of &$var parameters after function calls	Medium	Type Inference	type-inference.md §7
47	SPL iterator generic stubs	Medium	Type Inference	type-inference.md §8
48	LanguageLevelTypeAware version-aware type hints	Medium	Completion	completion.md §2
49	#[ArrayShape] return shapes on stub functions	Medium	Completion	completion.md §3
50	Asymmetric visibility (PHP 8.4)	Low	Type Inference	type-inference.md §9
52	class_alias() support	Medium	Completion	completion.md §8
53	Attribute constructor signature help	Medium	Signature Help	signature-help.md §4
54	Closure/arrow function parameter signature help	Medium	Signature Help	signature-help.md §5
55	Diagnostic suppression intelligence	Medium	Diagnostics	diagnostics.md §6
56	Partial result streaming via $/progress	Medium-High	LSP Features	lsp-features.md §6

Note: Item 56 (partial result streaming) addresses outbound latency for large result sets. See also item 89 (incremental text sync) in the backlog, which addresses the complementary inbound direction.

---

Sprint 9 — Blade support

Blade is a multi-phase project tracked in todo/blade.md. Shipping Blade support makes PHPantom the first open-source PHP language server with Blade intelligence.

Phase	Scope	Key Items
Phase 1	Blade-to-PHP preprocessor	Module skeleton, directive translation, source map, LSP wiring
Phase 2	Component support	Template/component discovery, <x-component> parsing, @props/@aware, name completion
Phase 3	Cross-file view intelligence	View name GTD, signature merging for @extends, component→template variable typing
Phase 4	Blade directive completion	Directive name completion with snippet insertion

---

Backlog — Diminishing returns

These items improve accuracy in niche scenarios. They're worth doing eventually but don't move the needle.

Completion & type inference tail

#	Item	Effort	Domain	Doc Link
58	Array functions needing new code paths	High	Completion	completion.md §1
59	Go-to-definition for array shape keys via bracket access	Medium	Completion	completion.md §4
60	No go-to-definition for built-in (stub) functions and constants — superseded by item 91	Medium	LSP Features	external-stubs.md §1
61	str_contains / str_starts_with / str_ends_with → non-empty-string narrowing	Low	Type Inference	type-inference.md §10
62	count / sizeof comparison → non-empty-array narrowing	Low	Type Inference	type-inference.md §11
63	Fiber type resolution	Low	Type Inference	type-inference.md §12
64	Non-empty-string propagation through string functions	Low	Type Inference	type-inference.md §13
65	Closure::bind() / Closure::fromCallable() return type preservation	Low-Medium	Type Inference	type-inference.md §14
66	Non-array functions with dynamic return types	High	Completion	completion.md §5
67	#[ReturnTypeContract] parameter-dependent return types	Low	Completion	completion.md §6
68	#[ExpectedValues] parameter value suggestions	Medium	Completion	completion.md §7

Signature help polish

#	Item	Effort	Domain	Doc Link
69	Multiple overloaded signatures	Medium-High	Signature Help	signature-help.md §7
70	Named argument awareness in active parameter	Medium	Signature Help	signature-help.md §8
71	Language construct signature help and hover	Low	Signature Help	signature-help.md §9

LSP features & code actions

#	Item	Effort	Domain	Doc Link
72	Switch → match conversion	Medium	Code Actions	actions.md §4
89	Incremental text sync	Medium	Performance	performance.md §8
104	Unreachable code diagnostic	Low	Diagnostics	diagnostics.md §8
112	Generate interface from class	Medium	Code Actions	actions.md §13

Performance long-tail

#	Item	Effort	Domain	Doc Link
90	Type AST for apply_substitution (full refactor)	High	Performance	performance.md §7
96	Parallel pre-filter in find_implementors	Medium	Performance	performance.md §9
97	memmem for block comment terminator search	Low	Performance	performance.md §10
98	memmap2 for file reads during scanning	Low	Performance	performance.md §11
108	O(n²) transitive eviction in evict_fqn	Low	Performance	performance.md §12
109	diag_pending_uris uses Vec::contains for dedup	Low	Performance	performance.md §13
110	find_class_in_ast_map linear fallback scan	Low	Performance	performance.md §14
113	Granular progress reporting for indexing, GTI, and Find References	Medium	Indexing	indexing.md §5.5

External stubs

#	Item	Effort	Domain	Doc Link
92	Project-level stubs as type resolution source	Medium	External Stubs	external-stubs.md §2
93	IDE-provided and .phpantom.toml stub paths	Low	External Stubs	external-stubs.md §3
94	Ship SPL overlay stubs, let external stubs override	Low	External Stubs	external-stubs.md §4

---

Laravel-Specific Gaps

These are tracked in todo/laravel.md and ranked separately by their own impact÷effort scoring.

#	Item	Impact	Effort	Doc Link
L1	morphedByMany missing from relationship method map	★★	★	§1
L2	$dates array (deprecated)	★★	★★	§2
L3	Custom Eloquent builders	★★★★	★★★	§3
L4	abort_if/abort_unless type narrowing	★★★★	★★★	§4
L5	collect() generic type info	★★★★★	★★★★	§5
L6	Factory has*/for* relationship methods	★★	★★★	§6
L7	$pivot property on BelongsToMany	★★★	★★★★	§7
L8	withSum/withAvg/withMin/withMax aggregate properties	★★	★★★★	§8
L9	Higher-order collection proxies	★★	★★★★	§9
L11	View::withX() / RedirectResponse::withX() dynamic methods	★	★★	§11
L12	$appends array	★	★	§12
LF	Facade getFacadeAccessor resolution should beat @method static tags	★★★★	★★★	§Facades

---

Blade Support

Blade is a multi-phase project tracked in todo/blade.md.

Phase	Scope	Key Items
Phase 1	Blade-to-PHP preprocessor	Module skeleton, directive translation, source map, LSP wiring
Phase 2	Component support	Template/component discovery, <x-component> parsing, @props/@aware, name completion
Phase 3	Cross-file view intelligence	View name GTD, signature merging for @extends, component→template variable typing
Phase 4	Blade directive completion	Directive name completion with snippet insertion