Deprecate making __debugInfo() nullable (#21984)

* Deprecate making `__debugInfo()` nullable

Returning `null` is already deprecated since PHP 8.5
(3dc962b). Not deprecating a corresponding
return type seems like an oversight.

* NEWS / UPGRADING

Author: TimWolla

NEWS

@@ -18,6 +18,7 @@ PHP                                                                        NEWS
     initialization). (Arnaud)
   . Enabled the TAILCALL VM on Windows when compiling with Clang >= 19 x86_64.
     (henderkes)
+  . Deprecate specifying a nullable return type for __debugInfo(). (timwolla)
 
 - BCMath:
   . Added NUL-byte validation to BCMath functions. (jorgsowa)

UPGRADING

@@ -189,6 +189,10 @@ PHP 8.6 UPGRADE NOTES
 4. Deprecated Functionality
 ========================================
 
+- Core:
+  . Specifying a return type of array|null / ?array for __debugInfo() is now
+    deprecated. Specify array instead.
+
 - GMP
   . The shift (<<, >>) and exponentiation (**) operators on GMP objects now
     emit a deprecation warning when converting a float right operand to int

Zend/tests/debug_info/debug_info.phpt

@@ -21,13 +21,20 @@ class Bar {
   }
 }
 
+class Baz {
+  public function __debugInfo(): ?array {
+    return null;
+  }
+}
+
 $f = new Foo;
 var_dump($f);
 
 $b = new Bar;
 var_dump($b);
 ?>
 --EXPECTF--
+Deprecated: Returning null from Baz::__debugInfo() is deprecated, make the return type non-nullable and return an empty array instead in %s on line %d
 object(Foo)#%d (3) {
   ["a"]=>
   int(1)

Zend/tests/magic_methods/magic_methods_inheritance_rules.phpt

@@ -66,5 +66,6 @@ class WidenedArgumentType extends NarrowedReturnType {
 
 echo 'No problems!';
 ?>
---EXPECT--
+--EXPECTF--
+Deprecated: Returning null from ValidMagicMethods::__debugInfo() is deprecated, make the return type non-nullable and return an empty array instead in %s on line %d
 No problems!

Zend/tests/return_types/042.phpt

@@ -20,5 +20,10 @@ class JustAnArray {
 
 echo 'No problems!';
 ?>
---EXPECT--
+--EXPECTF--
+Deprecated: Returning null from UnionType::__debugInfo() is deprecated, make the return type non-nullable and return an empty array instead in %s on line %d
+
+Deprecated: Returning null from UnionType2::__debugInfo() is deprecated, make the return type non-nullable and return an empty array instead in %s on line %d
+
+Deprecated: Returning null from UnionTypeOldStyle::__debugInfo() is deprecated, make the return type non-nullable and return an empty array instead in %s on line %d
 No problems!

Zend/zend_API.c

@@ -2825,6 +2825,10 @@ ZEND_API void zend_check_magic_method_implementation(const zend_class_entry *ce,
 		zend_check_magic_method_non_static(ce, fptr, error_type);
 		zend_check_magic_method_public(ce, fptr);
 		zend_check_magic_method_return_type(ce, fptr, error_type, (MAY_BE_ARRAY | MAY_BE_NULL));
+		if ((fptr->common.fn_flags & ZEND_ACC_HAS_RETURN_TYPE) && ZEND_TYPE_PURE_MASK(fptr->common.arg_info[-1].type) & MAY_BE_NULL) {
+			zend_error(E_DEPRECATED, "Returning null from %s::__debugInfo() is deprecated, make the return type non-nullable and return an empty array instead",
+				ZSTR_VAL(ce->name));
+		}
 	} else if (zend_string_equals_literal(lcname, "__serialize")) {
 		zend_check_magic_method_args(0, ce, fptr, error_type);
 		zend_check_magic_method_non_static(ce, fptr, error_type);

ext/simplexml/simplexml.stub.php

@@ -51,7 +51,7 @@ public function getName(): string {}
 
     public function __toString(): string {}
 
-    public function __debugInfo(): ?array {}
+    public function __debugInfo(): array {}
 
     /** @tentative-return-type */
     public function count(): int {}