substr(): Passing null to parameter #1 ($string) of type string is deprecated ? Why PHP 8.1
Upgrading from PHP 7 or 8.0 to PHP 8.1 often triggers immediate friction in codebases that relied on loose typing. A common culprit is the substr() function, which suddenly refuses to accept null as its first argument. The error message Deprecated: substr(): Passing null to parameter #1 ($string) of type string is deprecated indicates a fundamental shift in how PHP handles function parameters. This deprecation signals that passing null where a string is expected is no longer acceptable behavior, even if the code previously executed without errors.
The root cause lies in the strict typing introduced in PHP 8.1 regarding scalar types. In earlier versions, PHP would implicitly cast null to an empty string within functions like substr(). While convenient, this masked bugs where data retrieval logic failed silently. Now, if your function callDescriptor('h1') returns null, passing that value to substr() triggers the warning because the type declaration explicitly requires a non-null string.
To resolve this, you must ensure that $h1 is always a valid string before calling substr(). The most robust approach involves adding a guard clause or using null coalescing to provide a default fallback value. Here is how you can refactor the provided example:
function getH1()
{
$h1 = callDescriptor('h1');
// Ensure $h1 is a string; fall back to an empty string if null
if ($h1 === null) {
$h1 = '';
}
return ucfirst(substr($h1, 0, 56));
}
Alternatively, you can use the null coalescing operator (??) for a more concise solution:
function getH1()
{
$h1 = callDescriptor('h1') ?? '';
return ucfirst(substr($h1, 0, 56));
}
Both approaches effectively prevent the deprecation warning by guaranteeing that substr() receives a string. However, simply suppressing the error is not recommended. Silencing warnings with @ or custom error handlers often hides critical logic failures where data retrieval returns null for a valid reason. Instead, treat null as an invalid state that requires handling at the source of the data fetch.
If you are working within a Laravel application, this issue frequently arises when accessing optional relationships or configuration values that might be missing. For instance, if callDescriptor retrieves a database field that is nullable, you must handle the absence of data explicitly. In such cases, ensuring the string context before passing it to string manipulation functions is best practice.
For larger codebases, this deprecation serves as a valuable indicator to audit all usages of substr, strpos, and similar string functions. They are among the most common points where null-coalescing or explicit type casting is required in PHP 8.1+. Ignoring these warnings can lead to runtime errors in future PHP versions, as deprecations often become fatal errors later on.
If you need more guidance on handling nullable types and strict typing in your PHP projects, resources like https://laravelcompany.com can provide deeper insights into modern PHP practices and type safety strategies.