Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

PHP says a null argument is not allowed for a typed parameter

ErrorDeprecated: Passing null to parameter #2 ($needle) of type string is deprecated

Short answer

PHP treats null as a value of its own type. A parameter typed string or int does not accept it unless the type says so. In your own functions this is a TypeError; for built-in functions PHP 8.1 and later raise a deprecation. Fix it by marking the type nullable with ?T or T|null, or by passing a real value.

  • Applies to PHP 8.1, PHP 8.3, PHP 8.4
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Read the message and the file and line it names. A TypeError names your own function; a Deprecated notice that names a built-in function (str_contains, strlen, trim and so on) points to a built-in call that received null.

    php -v && php -l path/to/file.php
  2. 2Match what you see, then jump to its fix

    1. 1Uncaught TypeError: ... Argument #1 ($c) must be of type CYour own function declares a non-nullable typeFix
    2. 2Deprecated: Passing null to parameter #2 ($needle) of type string is deprecatedA built-in function received null (PHP 8.1 and later)Fix
    3. 3A Deprecated notice about a parameter written as Type $x = nullA typed parameter is made nullable only by a null default (PHP 8.4 deprecates this)Fix

What does the error look like?

  • Deprecated: Passing null to parameter #2 ($needle) of type string is deprecated
  • Uncaught TypeError: f(): Argument #1 ($c) must be of type C

Cause 1 of 3

Your own function declares a non-nullable type

1Check

Find the function signature and the call that passes null. A parameter typed C or string accepts only that type unless null is allowed explicitly.

grep -rn "function f(" src/

2Fix

If null is a valid input, make the type nullable. ?C and C|null mean the same thing; ?T works since PHP 7.1 and T|null since PHP 8.0. If null is not valid, find where the value goes missing and fix the caller.

function f(?C $c)
{
    if ($c === null) {
        return;
    }
}

3Verify

Call the function with null and with a real object. Neither call should raise a TypeError.

php -r 'require "src/f.php"; f(null); f(new C); echo "ok\n";'

Confirmed by php.net

Did this fix it?

Cause 2 of 3

A built-in function received null (PHP 8.1 and later)

1Check

Before 8.1, built-in functions accepted null for scalar parameters. Since 8.1 this is deprecated, so old code that passes an unset variable or a missing array key now logs a notice. The line number points at the call.

php -d error_reporting=E_ALL -d display_errors=1 index.php

2Fix

Give the function a real value of the expected type. Use a default when null is expected, and do not cast blindly if a missing value should be treated as an error.

$needle = $maybeNull ?? '';
var_dump(str_contains("foobar", $needle));

3Verify

Run the same script again. The Deprecated line for that call should be gone.

php -d error_reporting=E_ALL -d display_errors=1 index.php

Confirmed by php.net

Did this fix it?

Cause 3 of 3

A typed parameter is made nullable only by a null default (PHP 8.4 deprecates this)

1Check

Search for typed parameters whose only way to accept null is the default value.

grep -rnE "function .*\b[A-Za-z_\\]+ \$[a-z_]+ = null" src/

2Fix

State the nullable type explicitly. The manual says implicit nullability through a null default is not recommended and is deprecated since PHP 8.4.

// before
function f(C $c = null) {}
// after
function f(?C $c = null) {}

3Verify

Run the file under PHP 8.4 with all errors on.

php -d error_reporting=E_ALL -d display_errors=1 -l src/f.php

Confirmed by php.net

Did this fix it?

How do I stop it coming back?

  • Declare nullable types explicitly (?T) wherever null is a legal input.
  • Run tests and CI with error_reporting set to E_ALL so deprecations show up before an upgrade.
  • Read the 8.x migration pages before raising the PHP version in production.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Back end

Apache returns 403 when a URL contains %3F

a request like /page%3Fname=test is refused while /page?name=test works

Recent Apache httpd blocks a rewrite when the request contains an encoded question mark (%3F) and the rewritten target has a literal ?.

2 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.