Add #[\Deprecated] attribute

beberlei · TimWolla · TimWolla · commit 4395ef48788d · 2024-04-19T13:36:03.000+02:00
Co-authored-by: Tim Düsterhus &lt;tim@tideways-gmbh.com&gt;
diff --git a/Zend/tests/attributes/deprecated_001.phpt b/Zend/tests/attributes/deprecated_001.phpt
@@ -0,0 +1,47 @@
+--TEST--
+#[Deprecated] attribute
+--FILE--
+<?php
+
+error_reporting(E_ALL | E_DEPRECATED);
+ini_set('display_errors', true);
+
+#[Deprecated]
+function test() {
+}
+
+#[Deprecated("use test() instead")]
+function test2() {
+}
+
+class Clazz {
+    #[Deprecated]
+    function test() {
+    }
+
+    #[Deprecated("use test() instead")]
+    function test2() {
+    }
+}
+
+test();
+test2();
+call_user_func("test");
+
+$cls = new Clazz();
+$cls->test();
+$cls->test2();
+
+call_user_func([$cls, "test"]);
+--EXPECTF--
+Deprecated: Function test() is deprecated in %s
+
+Deprecated: Function test2() is deprecated, use test() instead in %s
+
+Deprecated: Function test() is deprecated in %s
+
+Deprecated: Method Clazz::test() is deprecated in %s
+
+Deprecated: Method Clazz::test2() is deprecated, use test() instead in %s
+
+Deprecated: Method Clazz::test() is deprecated in %s
diff --git a/Zend/tests/attributes/deprecated_002.phpt b/Zend/tests/attributes/deprecated_002.phpt
@@ -0,0 +1,28 @@
+--TEST--
+#[Deprecated] attribute
+--FILE--
+<?php
+
+#[Deprecated()]
+function test() {
+}
+
+#[Deprecated("use test() instead")]
+function test2() {
+}
+
+$reflection = new ReflectionFunction('test');
+var_dump($reflection->getAttributes()[0]->newInstance());
+
+$reflection = new ReflectionFunction('test2');
+var_dump($reflection->getAttributes()[0]->newInstance());
+
+--EXPECTF--
+object(Deprecated)#3 (1) {
+  ["message"]=>
+  NULL
+}
+object(Deprecated)#2 (1) {
+  ["message"]=>
+  string(18) "use test() instead"
+}
diff --git a/Zend/tests/attributes/deprecated_003.phpt b/Zend/tests/attributes/deprecated_003.phpt
@@ -0,0 +1,12 @@
+--TEST--
+#[Deprecated] attribute with wrong type
+--FILE--
+<?php
+
+#[Deprecated(1234)]
+function test() {
+}
+
+
+--EXPECTF--
+Fatal error: Deprecated::__construct: Argument #1 ($message) must be of type string, int given in %s
diff --git a/Zend/zend_attributes.c b/Zend/zend_attributes.c
@@ -30,6 +30,7 @@ ZEND_API zend_class_entry *zend_ce_allow_dynamic_properties;
 ZEND_API zend_class_entry *zend_ce_sensitive_parameter;
 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_attribute;
 
 static zend_object_handlers attributes_object_handlers_sensitive_parameter_value;
 
@@ -80,6 +81,32 @@ static void validate_allow_dynamic_properties(
 	scope->ce_flags |= ZEND_ACC_ALLOW_DYNAMIC_PROPERTIES;
 }
 
+void validate_deprecated_attribute(zend_attribute *attr, uint32_t target, zend_class_entry *scope)
+{
+	// TODO: More proper signature validation: Too many args, incorrect arg names.
+	if (attr->argc == 1) {
+		zval message;
+
+		/* As this is run in the middle of compilation, fetch the attribute value without
+		* specifying a scope. The class is not fully linked yet, and we may seen an
+		* inconsistent state. */
+		if (FAILURE == zend_get_attribute_value(&message, attr, 0, NULL)) {
+			return;
+		}
+
+		if (Z_TYPE(message) != IS_STRING) {
+			zval_ptr_dtor(&message);
+
+			zend_error_noreturn(E_COMPILE_ERROR,
+				"Deprecated::__construct: Argument #1 ($message) must be of type string, %s given",
+				zend_zval_type_name(&message)
+			);
+		}
+
+		zval_ptr_dtor(&message);
+	}
+}
+
 ZEND_METHOD(Attribute, __construct)
 {
 	zend_long flags = ZEND_ATTRIBUTE_TARGET_ALL;
@@ -142,6 +169,22 @@ ZEND_METHOD(Override, __construct)
 	ZEND_PARSE_PARAMETERS_NONE();
 }
 
+ZEND_METHOD(Deprecated, __construct)
+{
+	zend_string *message = NULL;
+
+	ZEND_PARSE_PARAMETERS_START(0, 1)
+		Z_PARAM_OPTIONAL
+		Z_PARAM_STR_OR_NULL(message)
+	ZEND_PARSE_PARAMETERS_END();
+
+	if (message) {
+		ZVAL_STR(OBJ_PROP_NUM(Z_OBJ_P(ZEND_THIS), 0), message);
+	} else {
+		ZVAL_NULL(OBJ_PROP_NUM(Z_OBJ_P(ZEND_THIS), 0));
+	}
+}
+
 static zend_attribute *get_attribute(HashTable *attributes, zend_string *lcname, uint32_t offset)
 {
 	if (attributes) {
@@ -380,6 +423,10 @@ void zend_register_attribute_ce(void)
 
 	zend_ce_override = register_class_Override();
 	zend_mark_internal_attribute(zend_ce_override);
+
+	zend_ce_deprecated_attribute = register_class_Deprecated();
+	attr = zend_mark_internal_attribute(zend_ce_deprecated_attribute);
+	attr->validator = validate_deprecated_attribute;
 }
 
 void zend_attributes_shutdown(void)
diff --git a/Zend/zend_attributes.stub.php b/Zend/zend_attributes.stub.php
@@ -71,3 +71,12 @@ final class Override
 {
     public function __construct() {}
 }
+
+/**
+ * @strict-properties
+ */
+#[Attribute(Attribute::TARGET_METHOD|Attribute::TARGET_FUNCTION)]
+final class Deprecated
+{
+    public function __construct(?string $message = null) {}
+}
diff --git a/Zend/zend_attributes_arginfo.h b/Zend/zend_attributes_arginfo.h
diff --git a/Zend/zend_compile.c b/Zend/zend_compile.c
@@ -7795,6 +7795,7 @@ static void zend_compile_func_decl(znode *result, zend_ast *ast, bool toplevel)
 	zend_ast *return_type_ast = decl->child[3];
 	bool is_method = decl->kind == ZEND_AST_METHOD;
 	zend_string *lcname;
+	zend_attribute *deprecated;
 
 	zend_class_entry *orig_class_entry = CG(active_class_entry);
 	zend_op_array *orig_op_array = CG(active_op_array);
@@ -7890,6 +7891,12 @@ static void zend_compile_func_decl(znode *result, zend_ast *ast, bool toplevel)
 		zend_compile_closure_uses(uses_ast);
 	}
 
+	deprecated = zend_get_attribute_str(op_array->attributes, "deprecated", sizeof("deprecated")-1);
+
+	if (deprecated && stmt_ast != NULL) {
+		op_array->fn_flags |= ZEND_ACC_DEPRECATED;
+	}
+
 	if (ast->kind == ZEND_AST_ARROW_FUNC && decl->child[2]->kind != ZEND_AST_RETURN) {
 		bool needs_return = true;
 		if (op_array->fn_flags & ZEND_ACC_HAS_RETURN_TYPE) {
diff --git a/Zend/zend_execute.c b/Zend/zend_execute.c
@@ -43,6 +43,7 @@
 #include "zend_observer.h"
 #include "zend_system_id.h"
 #include "zend_call_stack.h"
+#include "zend_attributes.h"
 #include "Optimizer/zend_func_info.h"
 
 /* Virtual current working directory support */
@@ -1724,13 +1725,45 @@ ZEND_API ZEND_COLD void zend_wrong_string_offset_error(void)
 
 ZEND_API ZEND_COLD void ZEND_FASTCALL zend_deprecated_function(const zend_function *fbc)
 {
-	if (fbc->common.scope) {
-		zend_error(E_DEPRECATED, "Method %s::%s() is deprecated",
-			ZSTR_VAL(fbc->common.scope->name),
-			ZSTR_VAL(fbc->common.function_name)
-		);
+	zend_attribute *deprecated;
+	zend_string *message_suffix = NULL;
+
+	if (fbc->common.attributes != NULL) {
+		deprecated = zend_get_attribute_str(fbc->common.attributes, "deprecated", sizeof("deprecated")-1);
+
+		if (deprecated->argc >= 1) {
+			zval message;
+
+			if (FAILURE != zend_get_attribute_value(&message, deprecated, 0, fbc->common.scope)) {
+				message_suffix = Z_STR(message);
+			}
+		}
+	}
+
+	if (message_suffix != NULL) {
+		if (fbc->common.scope) {
+			zend_error(E_DEPRECATED, "Method %s::%s() is deprecated, %s",
+				ZSTR_VAL(fbc->common.scope->name),
+				ZSTR_VAL(fbc->common.function_name),
+				ZSTR_VAL(message_suffix)
+			);
+		} else {
+			zend_error(E_DEPRECATED, "Function %s() is deprecated, %s",
+				ZSTR_VAL(fbc->common.function_name),
+				ZSTR_VAL(message_suffix)
+			);
+		}
+
+		zend_string_release(message_suffix);
 	} else {
-		zend_error(E_DEPRECATED, "Function %s() is deprecated", ZSTR_VAL(fbc->common.function_name));
+		if (fbc->common.scope) {
+			zend_error(E_DEPRECATED, "Method %s::%s() is deprecated",
+				ZSTR_VAL(fbc->common.scope->name),
+				ZSTR_VAL(fbc->common.function_name)
+			);
+		} else {
+			zend_error(E_DEPRECATED, "Function %s() is deprecated", ZSTR_VAL(fbc->common.function_name));
+		}
 	}
 }
 
diff --git a/Zend/zend_vm_def.h b/Zend/zend_vm_def.h
@@ -4048,6 +4048,10 @@ ZEND_VM_HOT_HANDLER(130, ZEND_DO_UCALL, ANY, ANY, SPEC(RETVAL,OBSERVER))
 	zend_function *fbc = call->func;
 	zval *ret;
 
+	if (UNEXPECTED((fbc->common.fn_flags & ZEND_ACC_DEPRECATED) != 0)) {
+		zend_deprecated_function(fbc);
+	}
+
 	SAVE_OPLINE();
 	EX(call) = call->prev_execute_data;
 
@@ -4082,6 +4086,10 @@ ZEND_VM_HOT_HANDLER(131, ZEND_DO_FCALL_BY_NAME, ANY, ANY, SPEC(RETVAL,OBSERVER))
 			ret = EX_VAR(opline->result.var);
 		}
 
+		if (UNEXPECTED((fbc->common.fn_flags & ZEND_ACC_DEPRECATED) != 0)) {
+			zend_deprecated_function(fbc);
+		}
+
 		call->prev_execute_data = execute_data;
 		execute_data = call;
 		i_init_func_execute_data(&fbc->op_array, ret, 0 EXECUTE_DATA_CC);
@@ -4180,6 +4188,10 @@ ZEND_VM_HOT_HANDLER(60, ZEND_DO_FCALL, ANY, ANY, SPEC(RETVAL,OBSERVER))
 			ret = EX_VAR(opline->result.var);
 		}
 
+		if (UNEXPECTED((fbc->common.fn_flags & ZEND_ACC_DEPRECATED) != 0)) {
+			zend_deprecated_function(fbc);
+		}
+
 		call->prev_execute_data = execute_data;
 		execute_data = call;
 		i_init_func_execute_data(&fbc->op_array, ret, 1 EXECUTE_DATA_CC);
diff --git a/Zend/zend_vm_execute.h b/Zend/zend_vm_execute.h

Original file line number	Diff line number	Diff line change
`@@ -71,3 +71,12 @@ final class Override`
`71`	`71`	`{`
`72`	`72`	`public function __construct() {}`
`73`	`73`	`}`
	`74`	`+`
	`75`	`+/**`
	`76`	`+ * @strict-properties`
	`77`	`+ */`
	`78`	`+#[Attribute(Attribute::TARGET_METHOD\|Attribute::TARGET_FUNCTION)]`
	`79`	`+final class Deprecated`
	`80`	`+{`
	`81`	`+ public function __construct(?string $message = null) {}`
	`82`	`+}`