[php-src] PR #21317: Reified generics

From: Date: Sat, 28 Feb 2026 18:47:20 +0000
Subject: [php-src] PR #21317: Reified generics
Groups: php.git-pulls 
Request: Send a blank email to git-pulls+get-35058@lists.php.net to get a copy of this message
Pull Request: https://github.com/php/php-src/pull/21317 Author: php-generics # Add reified generics to PHP ## Summary This PR adds reified generics to the Zend Engine — generic type parameters that are preserved at runtime and enforced through the type system. Unlike type erasure (Java/TypeScript), generic type arguments are bound per-instance and checked at every type boundary. **59 files changed**, **~2,900 lines added**, **55 tests**, **0 regressions** across 5,229 Zend tests. ## Syntax ### Generic classes ```php class Box<T> { public T $value; public function __construct(T $value) { $this->value = $value; } public function get(): T { return $this->value; } } $box = new Box<int>(42); // explicit type arg $box = new Box(42); // inferred from constructor — T = int $box->value = "hello"; // TypeError: cannot assign string to property Box<int>::$value of type int ``` ### Multiple type params, constraints, defaults ```php class Map<K: int|string, V = mixed> { // K is constrained to int|string, V defaults to mixed } class NumberBox<T: int|float> { public function sum(T $a, T $b): T { return $a + $b; } } ``` ### Variance annotations ```php class ReadOnlyList<out T> { /* covariant — can return T, not accept T */ } class Consumer<in T> { /* contravariant — can accept T, not return T */ } ``` ### Wildcard types ```php function printAll(Collection<? extends Printable> $items): void { ... } function addDogs(Collection<? super Dog> $kennel): void { ... } function count(Collection<?> $any): int { ... } ``` ### Generic traits ```php trait Cacheable<T> { private ?T $cached = null; public function cache(T $value): void { $this->cached = $value; } } class UserCache { use Cacheable<User>; } ``` ### Generic functions and closures ```php function identity<T>(T $x): T { return $x; } $map = function<T>(array $items, Closure $fn): array<T> { ... }; ``` ### Nested generics ```php $nested = new Box<Box<int>>(new Box<int>(42)); // >> handled by lexer splitting ``` ### Static method calls with generics ```php $result = Factory<int>::create(); ``` ### instanceof with generics ```php if ($obj instanceof Collection<int>) { ... } ``` ### Inheritance ```php class IntBox extends Box<int> {} // bound generic args class PairBox<A, B> extends Box<A> {} // forwarded params // Method signatures verified against parent's resolved types ``` ## Runtime enforcement All type boundaries are checked at runtime: - **Constructor args** — new Box<int>("x") throws TypeError - **Method params** — $box->set("x") throws TypeError when T = int - **Return types** — return "x" from a method declared (): T with T = int throws TypeError - **Property writes** — $box->value = "x" throws TypeError - **Error messages** include resolved types: Cannot assign string to property Box<int>::$value of type int ## Ecosystem integration - **Reflection** — ReflectionClass::isGeneric(), ::getGenericParameters(), ReflectionObject::getGenericArguments(), ReflectionGenericParameter (name, constraint, default, variance) - **Serialization** — serialize(new Box<int>(42)) produces O:8:"Box<int>":1:{...}, unserialize() restores generic args - **Debug display** — var_dump shows object(Box<int>)#1, stack traces show Box<int>->method() - **Opcache** — SHM persistence and file cache serialization - **JIT** — inline monomorphization with pre-computed bitmask fast path ## Edge cases covered - Anonymous classes (new class extends Box<int> {}) - Clone preserves generic args - Autoloading (Collection<int> triggers autoload for Collection) - class_alias inherits generic params - WeakReference/WeakMap with generic objects - Fibers across suspend/resume - Type argument forwarding (new Box<T>() inside generic methods/factories resolves T from context) - Compile-time rejection of void/never as type args ## Performance Benchmarked at 1M, 10M, and 100M iterations on arm64, both master (PHP 8.5.3 NTS) and generics branch (PHP 8.5.4-dev NTS) built as release binaries. Generic args use refcounted sharing — new Box<int>() adds a refcount instead of deep-copying, eliminating 4 allocator round-trips per object lifecycle. Pre-computed scalar bitmasks are stored inline (no separate allocation). ### Generic vs non-generic overhead (same binary) Results stabilize at higher iteration counts as warmup and noise are amortized. | Operation | 1M interp / JIT | 10M interp / JIT | 100M interp / JIT | |---|---|---|---| | Object creation | -8% / -10% | -7% / -11% | -7% / -11% | | Method calls (set+get) | -16% / -9% | -14% / -10% | -14% / -10% | | Property assignment | -3% / +1% | -3% / +1% | -2% / +0% | | Memory per object | +0 bytes | +0 bytes | +0 bytes | ### Absolute throughput (generics branch, JIT, ops/sec) | Operation | 1M | 10M | 100M | |---|---|---|---| | new GenericBox<int>(42) | 37.3M | 37.1M | 37.4M | | GenericBox<int>->set+get | 60.3M | 57.7M | 60.2M | | GenericBox<int>->value = N | 94.9M | 93.1M | 94.2M | | new GenericBox<GenericBox<int>> | 22.0M | 22.0M | 21.9M | ### Non-generic regression check Non-generic classes (PlainBox, UntypedBox) were benchmarked on both master and the generics branch under identical conditions (release NTS, same image). Results at 100M iterations (most stable) confirm **zero performance regression** on existing code paths: | Operation | Class | master (JIT) | generics (JIT) | delta | |---|---|---|---|---| | Object creation | PlainBox | 41.3M ops/s | 42.0M ops/s | +2% | | Object creation | UntypedBox | 49.3M ops/s | 45.6M ops/s | -8% | | Method calls | PlainBox | 66.6M ops/s | 66.6M ops/s | +0% | | Method calls | UntypedBox | 77.0M ops/s | 77.4M ops/s | +0% | | Property assign | PlainBox | 96.1M ops/s | 94.1M ops/s | -2% | | Property assign | UntypedBox | 116.0M ops/s | 113.0M ops/s | -3% | | Memory | PlainBox | 94 bytes | 102 bytes | +8 bytes | | Memory | UntypedBox | 82 bytes | 90 bytes | +8 bytes | The +8 bytes per object is the generic_args pointer field added to zend_object (NULL for non-generic objects). Throughput deltas are within cross-build variance (+-5%); no systematic code path slowdown was observed. ### Memory overhead | Object type | bytes/obj | |---|---| | PlainBox (typed int) | 102 | | GenericBox\<int\> (explicit) | 102 | | GenericBox (inferred) | 122 | | GenericBox\<GenericBox\<int\>\> | 90 | Generic objects with explicit type args have **zero memory overhead** vs non-generic typed objects — refcounted args are shared with the compiled literal. Inferred args (+20 bytes) allocate a new args struct. Nested generics benefit most from sharing (90 bytes vs 210 bytes before optimization).

« previous php.git-pulls (#35058) next »