fix(php): resolve method calls through $this-> properties on their declared type (#1220)

[w0lan]

Fixes #1220

Problem

A PHP method call whose receiver is a class property — $this->dep->method(), the dominant call shape in constructor-injection codebases (Symfony, Laravel) — produces no calls edge. The extractor records the receiver as raw text (this->dep), which no resolution strategy can type, so the reference is dropped. codegraph_callers then reports a heavily-used method as uncalled (or test-only, since unit tests calling through local new receivers DO resolve), and impact analysis misses every production consumer. Full evidence and measurement protocol in #1220.

Fix

Three coordinated pieces, all riding existing machinery (no schema or extraction changes):

1. inferLocalReceiverType (name-matcher.ts): strip the PHP this-> prefix and widen the scan to the whole file — the same treatment CFML component-scoped fields (variables.svc / this.svc) already get in this function. The existing PHP typed-parameter pattern (Foo $prop) then recovers the type from a promoted constructor parameter, a typed property declaration, or a classic constructor parameter alike; nearest-declaration-backward still lets a shadowing local win.
2. matchMethodCall (name-matcher.ts): resolve the this->prop.method shape exclusively through declared-type inference + resolveMethodOnType validation at confidence 0.9 (the same tier as the Local-variable receiver-type inference is C++-only — instance method calls through a local don't resolve in other languages #1108/TypeScript/JavaScript: local-variable receiver-type inference doesn't cover typed function parameters (unlike Java/C#/Kotlin/Swift/Scala) #1125 typed paths). The name-similarity strategies below never see this shape, so a property whose type can't be recovered statically (docblock-only, setter/container injection) stays unlinked rather than guessed — a wrong inference produces no edge rather than a wrong one.
3. Defer + conformance retry (resolution/index.ts): a method the property's type inherits from a supertype is resolvable only once implements/extends edges exist, so refs matching PHP_PROP_SHAPE are pushed to the existing deferred-chain retry and dispatched back through matchMethodCall in the conformance pass — the Tracking: chained factory/singleton call resolution across statically-typed languages #750/TS/JS class fields with type annotations are extracted as method-kind nodes #808 lifecycle, no new wiring.

Validation

• 15-case corpus: promoted / classic / interface-typed / parent-class / trait properties, inherited method (via the conformance retry), two same-named methods on unrelated classes (edge goes to the property's declared type, not the first-indexed homonym), local variable shadowing a property (Local-variable receiver-type inference is C++-only — instance method calls through a local don't resolve in other languages #1108 path still wins), untyped docblock-only property (deliberately no edge), deep chain $this->a->b->m() (deliberately no edge, parity with other languages).
• 9 new vitest tests (__tests__/php-property-receiver-resolution.test.ts), modeled on the CFML receiver-inference tests; full suite passes.
• Six real PHP codebases (340–9 200 files, PHP 7.1–8.5, Symfony 3.2–8.0): a sampled repository method went 0/7 → 7/7 production callers; 49/49 manually verified property-receiver edges correct across five typed codebases, zero false positives in random samples of confidence-0.9 edges; +6 100 call edges on a 5 000-file Symfony repo (+3.8%). On an untyped symfony-1.x legacy codebase the fix simply doesn't fire (no recoverable types) — no new wrong edges there either.

Known limitations (deliberately out of scope, candidates for follow-ups)

• Fluent/instance chains $this->prop->inner()->outer() — the first hop now resolves, the second needs the <inner>().<method> re-encoding other languages got in C++: method calls through singletons, factories, and chained getters resolve to the wrong class (or not at all) #645/PHP: codegraph_callers misses chained calls on static-factory return values (Cls::for($x)->method(...)) — common Laravel per-credential client pattern #608.
• Nullsafe calls ($this->prop?->method()) — nullsafe_member_call_expression isn't in the PHP extractor's callTypes at all (affects every nullsafe call, not just property receivers).
• Types available only in @var docblocks, or injected via setters/containers, stay unlinked by design.

[colbymchenry]

Thank you for this — the report in #1220 was one of the best-diagnosed issues we've received (the receiver-shape table and the root-cause trace were both exactly right), and the fix followed the receiver-inference architecture precisely where it should.

We wanted this shipped without another review round-trip, so it landed via #1251, which carries your branch verbatim plus one hardening commit, with co-author credit to you in the merge commit and the changelog. The hardening: the whole-file scan reused the generic local-variable patterns (the CFML component-scope treatment), but in PHP a plain $prop local or parameter can never alias $this->prop — so a same-named variable in another method could mistype the property and mint a wrong 0.9-confidence edge (e.g. a helper's $greeter = new OtherGreeter() routing $this->greeter->greet() to OtherGreeter::greet). Property receivers now consult property-shaped declarations only, with an assignment-following fallback for classic untyped properties that keeps your multi-line-constructor and setter-injection coverage — details and the interference regression tests are in #1251.

Your three follow-up candidates (fluent second hops, nullsafe ?-> in the extractor's callTypes, docblock types) are all real — the nullsafe one especially, since it affects every ?-> call. PRs very welcome on any of them.

Closing in favor of #1251 — thanks again, this fixes the dominant call shape for every DI-style PHP codebase.