todo.md

PHPantom — Roadmap

This document tracks planned work for PHPantom. Each item links to a domain document with full context. Items are grouped into time-boxed sprints (roughly 1-2 weeks each) and a backlog of ideas not yet scheduled.

Guiding priorities: Completion accuracy → Type intelligence → Cross-file navigation → Diagnostics → Code actions → Performance.

Items inside each sprint are ordered by priority (top = do first): quick wins (low effort) before heavy lifts, dependencies before their dependents, and within the same effort tier by impact descending. The backlog is ordered by impact (descending), then effort (ascending) within the same impact tier.

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)

Scheduled Sprints

Sprint 5 — Polish for office adoption

#	Item	Impact	Effort
	Release 0.8.0

Note: F1 (Workspace symbol search), F2 (Document symbols), A8 (Implement interface methods), A9 (Auto import), D1 (Unknown class diagnostic), D3 (Unknown member diagnostic), and L4 (Custom Eloquent builders) were originally planned here but have already shipped.

Sprint 6 — 1.0 release, editor plugins & type intelligence

#	Item	Impact	Effort
	Clear refactoring gate	—	—
A35	Convert to arrow function (only non-void single-expression closures)	Low-Medium	Low
C2	#[ArrayShape] return shapes on stub functions	Medium	Medium
A3	Switch → match conversion	Low-Medium	Medium
A10	Generate interface from class	Low-Medium	Medium
D10	PHPMD diagnostic proxy	Low	Medium

Sprint 7 — 1.0 release & IDE extensions

#	Item	Impact	Effort
	Clear refactoring gate	—	—
E5	Extension stub coverage audit	Medium	Low
X1	Staleness detection and auto-refresh	Medium	Medium
E1	External stub packages (ide-helper, etc.)	Medium-High	Medium
E2	Project-level stubs as type resolution source (depends on E1)	Medium	Medium
E3	IDE-provided and .phpantom.toml stub paths (depends on E2)	Low-Medium	Low
E4	Stub version alignment with target PHP (depends on E1)	Medium	Medium
L11	Relation dot-notation string and column name string completion	Medium-High	Medium-High
X4	Full background indexing (workspace symbols, fast find-references)	Medium	High
L1	Facade completion	High	High
	Release 1.0.0 + IDE extensions

Sprint 8 — Blade support

#	Item	Impact	Effort
	Clear refactoring gate	—	—
BL1	Blade-aware code actions	Medium	Medium
BL2	Template and component file discovery	High	Medium
BL3	Component tag parsing (<x-...>, <livewire:...>, @props)	High	High
BL4	Component and view name completion	High	Medium
BL5	Go-to-definition for view names and components	Medium	Medium
BL6	@extends signature merging and component class typing	Medium	High
BL7	Blade directive completion	Medium	Low

Backlog

Items not yet assigned to a sprint. Worth doing eventually but unlikely to move the needle for most users.

#	Item	Impact	Effort
	Completion
C1	Array functions needing new code paths	Medium	High
C9	Lazy documentation via completionItem/resolve	Medium	Medium
C11	Smarter member ordering after -> / ::	Medium	Medium
C3	Go-to-definition for array shape keys via bracket access	Low-Medium	Medium
C7	class_alias() support	Low-Medium	Medium
C4	Non-array functions with dynamic return types	Low	High
C5	#[ReturnTypeContract] parameter-dependent return types	Low	Low
C6	#[ExpectedValues] parameter value suggestions	Low	Medium
C10	Deprecation markers on class-name completions from all sources	Low	Low
	Type Inference
T20	Type narrowing reconciliation engine (CNF clause algebra, sure/sureNot tracking)	Medium-High	High
T27	Per-expression type caching during forward walk	Medium-High	Medium
T28	Template inference depth priority (shallowest bound wins)	Medium	Low-Medium
T29	Definite vs possible variable existence tracking	Medium	Medium
T30	Literal type collapse limit	Low-Medium	Low
T6	Closure::bind() / Closure::fromCallable() return type preservation	Low-Medium	Low-Medium
T13	Closure variables lose callable signature detail	Low-Medium	Medium
T26	Globbed constant unions (Foo::BAR_*)	Low-Medium	Medium
T4	Non-empty-* type narrowing and propagation	Low	Low
T5	Fiber type resolution	Low	Low
T9	Dead-code elimination after never-returning calls	Low	Low-Medium
T10	Ternary expression as RHS of list destructuring	Low	Low-Medium
T11	Nested list destructuring	Low	Low-Medium
	Diagnostics
D5	External tool diagnostic suppression actions	Low	Low
D6	Unreachable code diagnostic	Low-Medium	Low
	Bug Fixes
	Code Actions
A40	Generate method from call	Medium-High	Medium
A41	Create class from non-existing name	Medium	Medium
A16	Snippet placeholder for extracted method name (lets the user type over the generated name immediately)	Medium	Low-Medium
A25	strpos → str_contains (PHP 8.0+)	Medium	Low
A28	Explicit nullable parameter type (PHP 8.4 deprecation)	Medium	Low
A29	Simplify boolean return (if (cond) return true; return false; → return cond;)	Low-Medium	Medium
A31	Remove always-else (extract guard clause)	Low-Medium	Medium
A34	Unified code action handler architecture (closure-based resolve, unified fix type)	Medium	Medium-High
A37	Simplify with ?-> (replace null-checked chains with the nullsafe operator)	Low-Medium	Medium
A38	Convert if/elseif chain to switch	Low-Medium	Medium
A39	Convert to string interpolation ('Hello ' . $name → "Hello $name")	Low	Low
A43	Update docblock generics	Low	Low-Medium
	PHPStan Code Actions
H4	assign.byRefForeachExpr — unset by-reference foreach variable	Medium	Medium
H13	property.notFound — declare missing property (same-class)	Medium	Medium
H15	Template bound from tip — add @template T of X	Medium	Medium
H16	match.unhandled — add missing match arms	Medium	Medium
H19	property.unused / method.unused — remove unused member	Low	Low
H20	generics.callSiteVarianceRedundant — remove redundant variance annotation	Low	Low
H23	instanceof.alwaysTrue — remove redundant instanceof check	Low	Low
H24	catch.neverThrown — remove unnecessary catch clause	Low	Low
	CLI Fix Rules
FX1	deprecated — replace deprecated symbol usage	Medium	Medium
FX2	unused_variable — remove unused variables	Medium	Medium
FX3	phpstan.return.unusedType — remove unused type from return union	Medium	Medium
FX4	phpstan.missingType.iterableValue — add @return with iterable type	Medium	Medium
FX5	phpstan.property.unused / phpstan.method.unused — remove unused member	Low	Low
FX6	phpstan.generics.callSiteVarianceRedundant — remove redundant variance	Low	Low
FX7	add_return_type — generate @return docblocks from function bodies	Medium-High	Medium
	LSP Features
F17	Class move with reference update	Medium	Medium-High
F18	Fix namespace/class name from PSR-4	Medium	Medium
F5	Call hierarchy (incoming/outgoing calls)	Medium	Medium
F2	Partial result streaming via $/progress	Medium	Medium-High
F7	Evaluatable expression support (DAP integration)	Low-Medium	Low
F8	Test ↔ implementation navigation via @covers	Low	Medium
	Signature Help
S1	Attribute constructor signature help	Medium	Medium
S2	Closure / arrow function parameter signature help	Medium	Medium
S3	Multiple overloaded signatures	Medium	Medium-High
S4	Named argument awareness in active parameter	Low-Medium	Medium
S5	Language construct signature help and hover	Low	Low
	Laravel
L3	$dates array (deprecated)	Low-Medium	Low
L6	Factory has*/for* relationship methods	Low-Medium	Medium
L7	$pivot property on BelongsToMany	Medium	Medium-High
L8	withSum/withAvg/withMin/withMax aggregate properties	Low-Medium	Medium-High
L9	Higher-order collection proxies	Low-Medium	Medium-High
L10	View::withX() / RedirectResponse::withX() dynamic methods	Low	Low
	External Stubs
E6	Stub install prompt for non-Composer projects	Low	Low
E7	Stub-based framework patches	Medium	Medium
	Performance / Eager Resolution
ER5	Mago-style separated metadata	High	High
P14	Eager docblock parsing into structured fields	Medium	Medium
P9	resolved_class_cache generic-arg specialisation	Medium	Medium
P11	Uncached base-resolution in build_scope_methods_for_builder	Low-Medium	Low
P3	Parallel pre-filter in find_implementors	Low-Medium	Medium
P4	memmem for block comment terminator search	Low	Low
P5	memmap2 for file reads during scanning	Low	Low
P6	O(n²) transitive eviction in evict_fqn	Low	Low
P7	diag_pending_uris uses Vec::contains for dedup	Low	Low
P8	find_class_in_uri_classes_index linear fallback scan	Low	Low
P12	find_or_load_function Phase 1.75 serial bottleneck	Low	Low
P17	mago-names resolution on the parse hot path	Medium	Low
P18	Subtype result caching (per-request HashMap for hierarchy walks)	Medium	Low
P19	Arena reuse on the parse hot path (thread-local Bump::reset() instead of Bump::new())	Medium	Low
P20	Content-hash gated resolution cache persistence	Medium	Medium
P21	Offset-shifting for cached diagnostics on partial edits	Medium	Medium
	Indexing
X3	Completion item detail on demand (completionItem/resolve)	Medium	Medium
X7	Recency tracking	Medium	Medium
X2	Parallel file processing — remaining work	Low-Medium	Medium
X5	Granular progress reporting for indexing, GTI, and Find References	Low-Medium	Medium
X8	Inverted reference index for O(k) find-references	Medium-High	Medium
X6	Disk cache (evaluate later)	Medium	High
	Inline Completion
N1	Template engine (type-aware snippets)	Medium	High
N2	N-gram prediction from PHP corpus	Medium	Very High
N3	Fine-tuned GGUF sidecar model	Medium	Very High