feat(zend, reflection): expose direct-ancestor type arguments on ReflectionClass

Signed-off-by: azjezz <azjezz@protonmail.com>

Author: azjezz

UPGRADING

@@ -262,6 +262,14 @@ PHP 8.6 UPGRADE NOTES
     ReflectionFunction, ReflectionMethod, closures, and arrow functions).
   . Added ReflectionClass::isGeneric() and
     ReflectionClass::getGenericParameters().
+  . Added ReflectionClass::getGenericArgumentsForParentClass(),
+    ReflectionClass::getGenericArgumentsForParentInterface(string $name),
+    and ReflectionClass::getGenericArgumentsForUsedTrait(string $name) for
+    inspecting the type arguments supplied at a class's own extends /
+    implements / use sites. Returns null when no type arguments were
+    specified for that ancestor at this class's clause site (consumers
+    enumerate ancestors via the existing getParentClass() / getInterfaces()
+    / getTraits() APIs).
   . Added ReflectionNamedType::hasGenericArguments() and
     ReflectionNamedType::getGenericArguments(). The arguments are returned
     as ReflectionType instances in source order (pre-erasure form);

Zend/zend_compile.c

@@ -9872,15 +9872,24 @@ static void zend_compile_use_trait(const zend_ast *ast) /* {{{ */
 		zend_ast *trait_ast = traits->child[i];
 
 		if (ce->ce_flags & ZEND_ACC_INTERFACE) {
-			zend_string *name = zend_ast_get_str(trait_ast);
+			zend_string *name = trait_ast->kind == ZEND_AST_GENERIC_NAMED_TYPE
+				? zend_ast_get_str(trait_ast->child[0])
+				: zend_ast_get_str(trait_ast);
 			zend_error_noreturn(E_COMPILE_ERROR, "Cannot use traits inside of interfaces. "
 				"%s is used in %s", ZSTR_VAL(name), ZSTR_VAL(ce->name));
 		}
 
-		ce->trait_names[ce->num_traits].name =
+		uint32_t trait_index = ce->num_traits;
+		ce->trait_names[trait_index].name =
 			zend_resolve_const_class_name_reference(trait_ast, "trait name");
-		ce->trait_names[ce->num_traits].lc_name = zend_string_tolower(ce->trait_names[ce->num_traits].name);
+		ce->trait_names[trait_index].lc_name = zend_string_tolower(ce->trait_names[trait_index].name);
 		ce->num_traits++;
+
+		if (trait_ast->kind == ZEND_AST_GENERIC_NAMED_TYPE) {
+			zend_type pre = zend_compile_pre_erasure_typename(trait_ast);
+			zend_generic_type_table_set_trait_use(
+				zend_generic_get_or_create_class_table(ce), trait_index, pre);
+		}
 	}
 
 	if (!adaptations) {
@@ -9916,6 +9925,12 @@ static void zend_compile_implements(zend_ast *ast) /* {{{ */
 		interface_names[i].name =
 			zend_resolve_const_class_name_reference(class_ast, "interface name");
 		interface_names[i].lc_name = zend_string_tolower(interface_names[i].name);
+
+		if (class_ast->kind == ZEND_AST_GENERIC_NAMED_TYPE) {
+			zend_type pre = zend_compile_pre_erasure_typename(class_ast);
+			zend_generic_type_table_set_implements(
+				zend_generic_get_or_create_class_table(ce), i, pre);
+		}
 	}
 
 	ce->num_interfaces = list->children;
@@ -10055,6 +10070,15 @@ static void zend_compile_class_decl(znode *result, const zend_ast *ast, bool top
 	if (extends_ast) {
 		ce->parent_name =
 			zend_resolve_const_class_name_reference(extends_ast, "class name");
+		/* Capture the pre-erasure type when the extends clause specifies type
+		 * arguments (e.g. `extends Box<int>`). For an interface declaration
+		 * this AST holds the list of parent interfaces; for class/trait it's
+		 * the single parent class. */
+		if (extends_ast->kind == ZEND_AST_GENERIC_NAMED_TYPE) {
+			zend_type pre = zend_compile_pre_erasure_typename(extends_ast);
+			zend_generic_type_table_set_extends(
+				zend_generic_get_or_create_class_table(ce), pre);
+		}
 	}
 
 	CG(active_class_entry) = ce;

ext/reflection/php_reflection.c

@@ -8665,6 +8665,97 @@ ZEND_METHOD(ReflectionNamedType, getGenericArguments)
 	}
 }
 
+static void reflection_build_named_args_list(zval *return_value, const zend_type *boxed,
+		zend_class_entry *declaring_class)
+{
+	if (!ZEND_TYPE_HAS_NAMED_WITH_ARGS(*boxed)) {
+		RETURN_NULL();
+	}
+
+	zend_type_named_with_args *named = ZEND_TYPE_NAMED_WITH_ARGS(*boxed);
+	array_init_size(return_value, named->count);
+	for (uint32_t i = 0; i < named->count; i++) {
+		zval entry;
+		reflection_type_factory_ex(named->args[i], &entry, false,
+			(zend_type) ZEND_TYPE_INIT_NONE(0),
+			declaring_class, NULL);
+		zend_hash_next_index_insert_new(Z_ARRVAL_P(return_value), &entry);
+	}
+}
+
+ZEND_METHOD(ReflectionClass, getGenericArgumentsForParentClass)
+{
+	reflection_object *intern;
+	zend_class_entry *ce;
+
+	ZEND_PARSE_PARAMETERS_NONE();
+	GET_REFLECTION_OBJECT_PTR(ce);
+
+	if (!ce->generic_types || !ce->generic_types->extends) {
+		RETURN_NULL();
+	}
+
+	reflection_build_named_args_list(return_value, ce->generic_types->extends, ce);
+}
+
+ZEND_METHOD(ReflectionClass, getGenericArgumentsForParentInterface)
+{
+	reflection_object *intern;
+	zend_class_entry *ce;
+	zend_string *name;
+
+	ZEND_PARSE_PARAMETERS_START(1, 1)
+		Z_PARAM_STR(name)
+	ZEND_PARSE_PARAMETERS_END();
+	GET_REFLECTION_OBJECT_PTR(ce);
+
+	if (!ce->generic_types || !ce->generic_types->implements) {
+		RETURN_NULL();
+	}
+
+	zval *zv;
+	ZEND_HASH_FOREACH_VAL(ce->generic_types->implements, zv) {
+		zend_type *boxed = (zend_type *) Z_PTR_P(zv);
+		if (ZEND_TYPE_HAS_NAMED_WITH_ARGS(*boxed)) {
+			zend_type_named_with_args *named = ZEND_TYPE_NAMED_WITH_ARGS(*boxed);
+			if (zend_string_equals_ci(named->name, name)) {
+				reflection_build_named_args_list(return_value, boxed, ce);
+				return;
+			}
+		}
+	} ZEND_HASH_FOREACH_END();
+	RETURN_NULL();
+}
+
+ZEND_METHOD(ReflectionClass, getGenericArgumentsForUsedTrait)
+{
+	reflection_object *intern;
+	zend_class_entry *ce;
+	zend_string *name;
+
+	ZEND_PARSE_PARAMETERS_START(1, 1)
+		Z_PARAM_STR(name)
+	ZEND_PARSE_PARAMETERS_END();
+	GET_REFLECTION_OBJECT_PTR(ce);
+
+	if (!ce->generic_types || !ce->generic_types->trait_uses) {
+		RETURN_NULL();
+	}
+
+	zval *zv;
+	ZEND_HASH_FOREACH_VAL(ce->generic_types->trait_uses, zv) {
+		zend_type *boxed = (zend_type *) Z_PTR_P(zv);
+		if (ZEND_TYPE_HAS_NAMED_WITH_ARGS(*boxed)) {
+			zend_type_named_with_args *named = ZEND_TYPE_NAMED_WITH_ARGS(*boxed);
+			if (zend_string_equals_ci(named->name, name)) {
+				reflection_build_named_args_list(return_value, boxed, ce);
+				return;
+			}
+		}
+	} ZEND_HASH_FOREACH_END();
+	RETURN_NULL();
+}
+
 PHP_MINIT_FUNCTION(reflection) /* {{{ */
 {
 	memcpy(&reflection_object_handlers, &std_object_handlers, sizeof(zend_object_handlers));

ext/reflection/php_reflection.stub.php

@@ -446,6 +446,35 @@ public function isGeneric(): bool {}
 
     /** @return list<ReflectionGenericTypeParameter> */
     public function getGenericParameters(): array {}
+
+    /**
+     * Returns the type arguments this class supplies at the parent-class extends
+     * site, in source order. Returns null if there is no parent class, or if
+     * the extends clause specified no type arguments.
+     *
+     * @return list<ReflectionType>|null
+     */
+    public function getGenericArgumentsForParentClass(): ?array {}
+
+    /**
+     * Returns the type arguments this class supplies for the named parent
+     * interface (a directly-listed `implements` entry, or, for an interface
+     * declaration, a directly-listed `extends` entry), in source order.
+     * Returns null if $name is not a directly-listed parent interface, or if
+     * no type arguments were specified at the use site.
+     *
+     * @return list<ReflectionType>|null
+     */
+    public function getGenericArgumentsForParentInterface(string $name): ?array {}
+
+    /**
+     * Returns the type arguments this class supplies at the use site for trait
+     * $name, in source order. Returns null if $name is not a directly-used
+     * trait, or if no type arguments were specified at the use site.
+     *
+     * @return list<ReflectionType>|null
+     */
+    public function getGenericArgumentsForUsedTrait(string $name): ?array {}
 }
 
 class ReflectionObject extends ReflectionClass

ext/reflection/php_reflection_arginfo.h

@@ -30,7 +30,7 @@ Class [ <internal:Reflection> class ReflectionClass implements Stringable, Refle
     Property [ public string $name ]
   }
 
-  - Methods [66] {
+  - Methods [69] {
     Method [ <internal:Reflection> private method __clone ] {
 
       - Parameters [0] {
@@ -528,5 +528,28 @@ Class [ <internal:Reflection> class ReflectionClass implements Stringable, Refle
       }
       - Return [ array ]
     }
+
+    Method [ <internal:Reflection> public method getGenericArgumentsForParentClass ] {
+
+      - Parameters [0] {
+      }
+      - Return [ ?array ]
+    }
+
+    Method [ <internal:Reflection> public method getGenericArgumentsForParentInterface ] {
+
+      - Parameters [1] {
+        Parameter #0 [ <required> string $name ]
+      }
+      - Return [ ?array ]
+    }
+
+    Method [ <internal:Reflection> public method getGenericArgumentsForUsedTrait ] {
+
+      - Parameters [1] {
+        Parameter #0 [ <required> string $name ]
+      }
+      - Return [ ?array ]
+    }
   }
 }

ext/reflection/php_reflection_decl.h

@@ -0,0 +1,19 @@
+--TEST--
+Reflection: composite (union/intersection) type args inside extends/implements
+--FILE--
+<?php
+class A {}
+class B {}
+class Pair<X, Y> {}
+
+class C extends Pair<A|B, A&B> {}
+
+$args = (new ReflectionClass('C'))->getGenericArgumentsForParentClass();
+echo "count: ", count($args), "\n";
+echo "[0] kind: ", get_class($args[0]), "\n";
+echo "[1] kind: ", get_class($args[1]), "\n";
+?>
+--EXPECT--
+count: 2
+[0] kind: ReflectionUnionType
+[1] kind: ReflectionIntersectionType

ext/reflection/tests/ReflectionClass_toString_001.phpt

@@ -0,0 +1,39 @@
+--TEST--
+Reflection: nested generic arguments inside extends/implements/use are preserved
+--FILE--
+<?php
+class Box<T> {}
+class Pair<K, V> {}
+interface I<X> {}
+trait T1<U> { public function noop(): void {} }
+
+class WithNested
+    extends Pair<Box<int>, string>
+    implements I<Box<float>>
+{
+    use T1<Box<bool>>;
+}
+
+$rc = new ReflectionClass('WithNested');
+
+// Nested in extends
+$args = $rc->getGenericArgumentsForParentClass();
+echo "parent[0]: ", $args[0]->getName();
+echo "<", $args[0]->getGenericArguments()[0]->getName(), ">\n";
+echo "parent[1]: ", $args[1]->getName(), "\n";
+
+// Nested in implements
+$args = $rc->getGenericArgumentsForParentInterface('I');
+echo "I[0]: ", $args[0]->getName();
+echo "<", $args[0]->getGenericArguments()[0]->getName(), ">\n";
+
+// Nested in use
+$args = $rc->getGenericArgumentsForUsedTrait('T1');
+echo "T1[0]: ", $args[0]->getName();
+echo "<", $args[0]->getGenericArguments()[0]->getName(), ">\n";
+?>
+--EXPECT--
+parent[0]: Box<int>
+parent[1]: string
+I[0]: Box<float>
+T1[0]: Box<bool>

ext/reflection/tests/generics/ancestor_args_composite.phpt

@@ -0,0 +1,26 @@
+--TEST--
+Reflection: classes with no generic content return null from all three accessors
+--FILE--
+<?php
+class Plain {}
+class WithParent extends Plain {}
+interface IPlain {}
+class WithIface implements IPlain {}
+trait TPlain { public function noop(): void {} }
+class WithTrait { use TPlain; }
+
+foreach (['Plain', 'WithParent', 'WithIface', 'WithTrait'] as $cls) {
+    $rc = new ReflectionClass($cls);
+    $p = $rc->getGenericArgumentsForParentClass();
+    $i = $rc->getGenericArgumentsForParentInterface('IPlain');
+    $t = $rc->getGenericArgumentsForUsedTrait('TPlain');
+    echo $cls, ": parent=", ($p === null ? "null" : "non-null"),
+         " iface=", ($i === null ? "null" : "non-null"),
+         " trait=", ($t === null ? "null" : "non-null"), "\n";
+}
+?>
+--EXPECT--
+Plain: parent=null iface=null trait=null
+WithParent: parent=null iface=null trait=null
+WithIface: parent=null iface=null trait=null
+WithTrait: parent=null iface=null trait=null