Add #[ClassAlias]

php · DanielEScherzer · Jun 6, 2025 · Jun 6, 2025 · Jun 7, 2025 · Jun 7, 2025
commit e1a37a8b7b75cba0527265479942ecba1c592886
diff --git a/Zend/tests/attributes/class_alias/parameter_invalid.phpt b/Zend/tests/attributes/class_alias/parameter_invalid.phpt
@@ -0,0 +1,11 @@
+--TEST--
+Alias name must be valid
+--FILE--
+<?php
+
+#[ClassAlias('never')]
+class Demo {}
+
+?>
+--EXPECTF--
+Fatal error: Cannot use "never" as a class alias as it is reserved in %s on line %d
diff --git a/Zend/tests/attributes/class_alias/parameter_nonstring.phpt b/Zend/tests/attributes/class_alias/parameter_nonstring.phpt
@@ -0,0 +1,11 @@
+--TEST--
+Parameter must be a string
+--FILE--
+<?php
+
+#[ClassAlias([])]
+class Demo {}
+
+?>
+--EXPECTF--
+Fatal error: ClassAlias::__construct(): Argument #1 ($alias) must be of type string, array given in %s on line %d
diff --git a/Zend/tests/attributes/class_alias/parameter_required.phpt b/Zend/tests/attributes/class_alias/parameter_required.phpt
@@ -0,0 +1,15 @@
+--TEST--
+Parameter is required
+--FILE--
+<?php
+
+#[ClassAlias]
+class Demo {}
+
+?>
+--EXPECTF--
+Fatal error: Uncaught ArgumentCountError: ClassAlias::__construct() expects exactly 1 argument, 0 given in %s:%d
+Stack trace:
+#0 %s(%d): ClassAlias->__construct()
+#1 {main}
+  thrown in %s on line %d
diff --git a/Zend/tests/attributes/class_alias/redeclaration_error.phpt b/Zend/tests/attributes/class_alias/redeclaration_error.phpt
@@ -0,0 +1,11 @@
+--TEST--
+Cannot redeclare an existing class
+--FILE--
+<?php
+
+#[ClassAlias('Attribute')]
+class Demo {}
+
+?>
+--EXPECTF--
+Fatal error: Unable to declare alias 'Attribute' for 'Demo' in %s on line %d
diff --git a/Zend/tests/attributes/class_alias/repeated_attribute.phpt b/Zend/tests/attributes/class_alias/repeated_attribute.phpt
@@ -0,0 +1,25 @@
+--TEST--
+Attribute can be repeated
+--FILE--
+<?php
+
+#[ClassAlias('First')]
+#[ClassAlias('Second')]
+class Demo {}
+
+var_dump( class_exists( 'First' ) );
+var_dump( class_exists( 'Second' ) );
+
+$obj1 = new First();
+var_dump( $obj1 );
+
+$obj2 = new Second();
+var_dump( $obj2 );
+?>
+--EXPECTF--
+bool(true)
+bool(true)
+object(Demo)#%d (0) {
+}
+object(Demo)#%d (0) {
+}
diff --git a/Zend/tests/attributes/class_alias/target_validation.phpt b/Zend/tests/attributes/class_alias/target_validation.phpt
@@ -0,0 +1,11 @@
+--TEST--
+Can only be used on classes
+--FILE--
+<?php
+
+#[ClassAlias]
+function demo() {}
+
+?>
+--EXPECTF--
+Fatal error: Attribute "ClassAlias" cannot target function (allowed targets: class) in %s on line %d
diff --git a/Zend/tests/attributes/class_alias/working_example.phpt b/Zend/tests/attributes/class_alias/working_example.phpt
@@ -0,0 +1,17 @@
+--TEST--
+Working usage
+--FILE--
+<?php
+
+#[ClassAlias('Other')]
+class Demo {}
+
+var_dump( class_exists( 'Other' ) );
+
+$obj = new Other();
+var_dump( $obj );
+?>
+--EXPECTF--
+bool(true)
+object(Demo)#%d (0) {
+}
diff --git a/Zend/zend_attributes.c b/Zend/zend_attributes.c
@@ -32,6 +32,7 @@ ZEND_API zend_class_entry *zend_ce_sensitive_parameter_value;
 ZEND_API zend_class_entry *zend_ce_override;
 ZEND_API zend_class_entry *zend_ce_deprecated;
 ZEND_API zend_class_entry *zend_ce_nodiscard;
+ZEND_API zend_class_entry *zend_ce_class_alias;
 
 static zend_object_handlers attributes_object_handlers_sensitive_parameter_value;
 
@@ -95,6 +96,46 @@ static void validate_allow_dynamic_properties(
 	scope->ce_flags |= ZEND_ACC_ALLOW_DYNAMIC_PROPERTIES;
 }
 
+static void validate_class_alias(
+		zend_attribute *attr, uint32_t target, zend_class_entry *scope)
+{
+	zval alias_obj;
+	ZVAL_UNDEF(&alias_obj);
+	zend_result result = zend_get_attribute_object(
+		&alias_obj,
+		zend_ce_class_alias,
+		attr,
+		scope,
+		scope->info.user.filename
+	);
+	if (result == FAILURE) {
+		ZEND_ASSERT(EG(exception));
+		return;
+	}
+
+	zval *alias_name = zend_read_property(
+		zend_ce_class_alias,
+		Z_OBJ(alias_obj),
+		ZEND_STRL("alias"),
+		false,
+		NULL
+	);
+	result = zend_register_class_alias_ex(
+		Z_STRVAL_P(alias_name),
+		Z_STRLEN_P(alias_name),
+		scope,
+		false
+	);
+	if (result == FAILURE) {
+		zend_error_noreturn(E_ERROR, "Unable to declare alias '%s' for '%s'",
+			Z_STRVAL_P(alias_name),
+			ZSTR_VAL(scope->name)
+		);
+	}
+	zval_ptr_dtor(alias_name);
+	zval_ptr_dtor(&alias_obj);
+}
+
 ZEND_METHOD(Attribute, __construct)
 {
 	zend_long flags = ZEND_ATTRIBUTE_TARGET_ALL;
@@ -217,6 +258,24 @@ ZEND_METHOD(NoDiscard, __construct)
 	}
 }
 
+ZEND_METHOD(ClassAlias, __construct)
+{
+	zend_string *alias = NULL;
+
+	ZEND_PARSE_PARAMETERS_START(1, 1)
+		Z_PARAM_STR(alias)
+	ZEND_PARSE_PARAMETERS_END();
+
+	zval value;
+	ZVAL_STR(&value, alias);
+	zend_update_property(zend_ce_class_alias, Z_OBJ_P(ZEND_THIS), ZEND_STRL("alias"), &value);
+
+	/* The assignment might fail due to 'readonly'. */
+	if (UNEXPECTED(EG(exception))) {
+		RETURN_THROWS();
+	}
+}
+
 static zend_attribute *get_attribute(HashTable *attributes, zend_string *lcname, uint32_t offset)
 {
 	if (attributes) {
@@ -548,6 +607,10 @@ void zend_register_attribute_ce(void)
 
 	zend_ce_nodiscard = register_class_NoDiscard();
 	attr = zend_mark_internal_attribute(zend_ce_nodiscard);
+
+	zend_ce_class_alias = register_class_ClassAlias();
+	attr = zend_mark_internal_attribute(zend_ce_class_alias);
+	attr->validator = validate_class_alias;
 }
 
 void zend_attributes_shutdown(void)

diff --git a/Zend/zend_attributes.stub.php b/Zend/zend_attributes.stub.php
@@ -97,3 +97,14 @@ final class NoDiscard
 
     public function __construct(?string $message = null) {}
 }
+
+/**
+ * @strict-properties
+ */
+#[Attribute(Attribute::TARGET_CLASS|Attribute::IS_REPEATABLE)]
+final class ClassAlias
+{
+    public readonly string $alias;
+
+    public function __construct(string $alias) {}
+}
diff --git a/Zend/zend_attributes_arginfo.h b/Zend/zend_attributes_arginfo.h