Implement constructor generic pre-binding and enhance runtime type ch…

[rcalicdan]

PR Notes

Overview

TypePHP now eagerly binds generic template contracts to class instances before __construct parameter validation executes when an inline /** @var ClassName<Type> */ annotation is defined on an instantiation assignment.

---

Key Improvements

1. Pre-Constructor Template Binding

Previously, constructor parameters were evaluated before variable-level @var annotations were processed. This caused generic constructors (__construct(array $items)) to infer template types dynamically from the first argument passed, rather than respecting the declared variable type contract.

TypePHP now pre-binds the promised generic type to the instance before constructor parameter validation begins.

2. Heterogeneous Collection Initialization

Collections and generic containers initialized with multiple union subtypes now validate seamlessly without premature type-locking:

/** @var Collection<Animal> $animals */
$animals = new Collection([new Dog(), new Cat()]);

3. Immediate Constructor Boundary Failures

Invalid constructor arguments fail fast and report the exact parameter index where the invalid data was passed:

/** @var Box<Animal> $box */
$box = new Box([1, 2, '3']);

// Throws:
// TypeError: Box::__construct(): Argument $content[0] (template T = Animal) must be of type Animal, int (1) given

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!