Deprecate passing null to non-nullable arg of internal function

This deprecates passing null to non-nullable scale arguments of
internal functions, with the eventual goal of making the behavior
consistent with userland functions, where null is never accepted
for non-nullable arguments.

This change is expected to cause quite a lot of fallout. In most
cases, calling code should be adjusted to avoid passing null. In
some cases, PHP should be adjusted to make some function arguments
nullable. I have already fixed a number of functions before landing
this, but feel free to file a bug if you encounter a function that
doesn't accept null, but probably should. (The rule of thumb for
this to be applicable is that the function must have special behavior
for 0 or "", which is distinct from the natural behavior of the
parameter.)

RFC: https://wiki.php.net/rfc/deprecate_null_to_scalar_internal_arg

Closes GH-6475.

1 files changed, 10 insertions, 0 deletions

diff --git a/UPGRADING b/UPGRADING
index 3014597868..2e4700c1c9 100644
--- a/UPGRADING
+++ b/UPGRADING
@@ -27,6 +27,16 @@ PHP 8.1 UPGRADE NOTES
     array is no longer supported. For example, array_pop($GLOBALS) will result
     in an error.
     RFC: https://wiki.php.net/rfc/restrict_globals_usage
+  . Passing null to a non-nullable argument of a built-in function is
+    deprecated. This matches the behavior of user-defined functions, where null
+    is never accepted by non-nullable arguments.
+    user-defined functions.
+
+        var_dump(str_contains("foobar", null));
+        // Deprecated: Passing null to parameter #2 ($needle) of type string
+        //             is deprecated
+
+    RFC: https://wiki.php.net/rfc/deprecate_null_to_scalar_internal_arg
 
 - Fileinfo:
   . The fileinfo functions now accept and return, respectively, finfo objects