[JGamboa]

Summary

Since the generics monomorphization (#1221), several plain-PHP @template patterns that
php-src runs (Laravel's and PHPStan-annotated code is full of them) are rejected or
miscompiled on main. This PR re-validates the follow-ups against main's current generics
(monomorphization, #1819, #1822) and fixes them:

Dynamically dispatched methods:

• an interface method's PHPDoc @template is erased: the interface keeps its native
  signature, so TInstance is no longer an Unknown type and implementations still
  conform;
• a templated method that implements a plain interface method, or overrides a parent
  method, keeps its vtable slot, so conformance and override dispatch work (main dispatched
  to the parent: Base 5 instead of Child 5);
• a @template-covariant marker that the declaration itself breaks (a writable property,
  a parameter) is demoted to invariant with a warning instead of rejecting a file php-src
  runs;
• PHPStan-style type arguments on undeclared (built-in) interfaces
  (@implements IteratorAggregate<string, int>, ArrayAccess<K, V>) are erased;
• a non-generic class that implements a PHPDoc-generic interface by its bare name still
  implements it (main: Unknown interface: Arrayable).

Templates and instanceof:

• each class or interface template leaves an empty marker interface that every
  instantiation inherits, so $x instanceof Coll holds for every instantiation and
  subclass, as in php-src (main: false for all of them); an instanceof guard on a
  template does not narrow to the member-less marker;
• a method template bounded by the native class (T of Model on Model) refines it; a
  template that no position adopts is dropped (the method compiles untyped, as php-src
  runs it); a native mixed is no longer replaced by PHPDoc;
• erased array<mixed, mixed> / mixed[] become plain array, so a dispatched method's
  physical signature stays compatible;
• methods implementing built-in interfaces (ArrayAccess, Countable, IteratorAggregate,
  JsonSerializable, ...) count as dispatched; any other undeclared ancestor makes every
  method dispatched.

Reflection: the marker a class template leaves behind is hidden from
interface_exists, get_declared_interfaces and class_implements, and
is_subclass_of($x, 'Box') holds only for a class extending an instantiation, as in
php-src. Interface-template markers stay visible. An instanceof guard on a template keeps
an object local's class and reads anything else as mixed.

The erasure rule is documented in docs/beyond-php/generics.md. There is no environment
switch to turn PHPDoc generics off.

The changes land as one commit because they share the docblock and generics passes; happy to
split it (dispatched-method erasure / template markers and instanceof / reflection) if you
prefer.

Closes #1899 (follow-up of #1221).

Changed upstream test

test_one_line_block_reads_its_opening_tag (from c769f6c) expected
does not determine type parameter <T> for the function, static method, trait method and
enum method forms of a one-line /** @template T of int @param T $v @return T */. With the
"a method template no position adopts is dropped" rule, the three METHOD forms now compile
untyped and print seven, which is what php-src prints. The function form and the
multi-line bound violation keep the upstream assertions.

Tests

18 new tests in tests/codegen/generics.rs and tests/codegen/generics_docblock_methods.rs.
Expected outputs come from php 8.5, except one native-syntax test (class Box<T>) that php
cannot parse.

• Fail on main: 17. 15 are compile errors (Unknown type: TInstance, Class ArrayRepo must implement interface method Repo::get, Unknown interface: Arrayable, a covariance error,
  'IteratorAggregate' is written with type arguments but declares no type parameters,
  Cannot implement interface method IntColl::first without declaring a compatible return type, ...). Two compile and print the wrong result: override dispatch (Base 5) and
  instanceof on a class template (all false).
• Control, passes on main: test_docblock_bounded_template_refines_the_native_bound
  (marked in its doc comment).

Based on main df57a98 (verified against a build of that SHA).

Local runs: cargo build; error_tests, parser_tests, lexer_tests;
codegen_tests -- generics docblock (290); lib tests for docblock, generics, source::
and narrowing; codegen instanceof class_implements interface_exists is_subclass_of declared_interfaces.

Refs #1886

AI assistance

This change was written with substantial help from Claude Code (Anthropic). I reviewed
it, checked the expected outputs against php 8.5, and remain responsible for it.

🤖 Generated with Claude Code

[greptile-apps]

Confidence Score: 4/5

[Medium impact] The changes affect how compiled PHP programs use PHPDoc generics.

Fix the newly broken explicit method calls before merging.

Findings

1.  Explicit method calls stop compiling ▶

Fix with agent prompt

### Issue 1
src/docblock/members.rs:118-120
Removing a template here breaks calls that compiled before this update. With separate `@template T`, `@param T $v`, and `@return T` tags on `public function id(mixed $v) { return $v; }`, `$repo->id<int>(7)` previously bound `T` explicitly.

This change removes `T` and restores the native return, so only ordinary `id` remains. The explicit call still looks for `id<int>` and fails with `Undefined method`. Preserve explicit calls while allowing ordinary calls to use the erased signature.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Summary

The PR erases templates on dispatched methods and adds shared markers for generic instanceof checks.

• PHPDoc templates keep the method contracts that dynamic calls need.
• Generic templates match every instantiation in instanceof checks.
• Generic interface annotations work with built-in and ordinary PHP interfaces.

_{Reviews (4) · Last reviewed commit: "fix(docblock): drop a method template wh..." · Reviewed by Greptile}

[greptile-apps]

Explicit method calls stop compiling

Removing a template here breaks calls that compiled before this update. With separate @template T, @param T $v, and @return T tags on public function id(mixed $v) { return $v; }, $repo->id<int>(7) previously bound T explicitly.

This change removes T and restores the native return, so only ordinary id remains. The explicit call still looks for id<int> and fails with Undefined method. Preserve explicit calls while allowing ordinary calls to use the erased signature.

Knowledge Base Used: Generic language support

Prompt To Fix With AI

This is a comment left during a code review.
Path: src/docblock/members.rs
Line: 118-120

Comment:
**Explicit method calls stop compiling**

Removing a template here breaks calls that compiled before this update. With separate `@template T`, `@param T $v`, and `@return T` tags on `public function id(mixed $v) { return $v; }`, `$repo->id<int>(7)` previously bound `T` explicitly.

This change removes `T` and restores the native return, so only ordinary `id` remains. The explicit call still looks for `id<int>` and fails with `Undefined method`. Preserve explicit calls while allowing ordinary calls to use the erased signature.

**Knowledge Base Used:** [Generic language support](https://app.greptile.com/illegal-studio/-/custom-context/knowledge-base/illegalstudio/elephc/-/docs/generic-language-support.md)

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.