Magento 2: How to Fix “str_replace() Deprecated” Warning in PHP 8.1+

When running Magento 2 on PHP 8.1 or later, you may encounter warnings related to str_replace() or similar string functions. These warnings usually appear because of deprecated usage patterns introduced in newer PHP versions. Let’s explore why this happens and how to fix it properly.

Understanding the Error

PHP 8.1 introduced stricter type checks and deprecated certain function usages. For example, calling str_replace() with null or invalid arguments can trigger warnings:

Deprecated: str_replace(): Passing null to parameter #3 ($subject) of type array|string is deprecated

This means that somewhere in your Magento code (or a custom module), str_replace() is being called with null instead of a valid string or array.

Common Causes in Magento

• Custom modules passing null values to str_replace().
• Third‑party extensions not updated for PHP 8.1 compatibility.
• Core code using older patterns that are now flagged as deprecated.

How to Fix It

The fix is straightforward: ensure that the subject parameter is always a string or array, not null.

Before (deprecated):

$output = str_replace('foo', 'bar', $value);

If $value is null, this triggers a warning.

After (fixed):

$output = str_replace('foo', 'bar', $value ?? '');

Here, the null coalescing operator (??) ensures that $value defaults to an empty string if it is null.

Alternative Fixes

• Type Casting → Cast the variable to string:

  $output = str_replace('foo', 'bar', (string)$value);

• Validation → Check before calling:

  if ($value !== null) {
      $output = str_replace('foo', 'bar', $value);
  }

Best Practices for PHP 8.1+ Compatibility

• Always validate input before passing to string functions.
• Use ?? '' or type casting to avoid null warnings.
• Update third‑party extensions to versions compatible with PHP 8.1.
• Run bin/magento setup:upgrade and clear caches after applying fixes.
• Enable display_errors in development to catch deprecations early.

Example in Magento Context

Suppose you have a helper method that manipulates product SKUs:

public function cleanSku($sku)
{
    return str_replace(' ', '-', $sku);
}

If $sku is null, this triggers a deprecation warning. Fix it like this:

public function cleanSku($sku)
{
    return str_replace(' ', '-', $sku ?? '');
}

This ensures compatibility with PHP 8.1+ and avoids unnecessary warnings.

Conclusion

The “str_replace() deprecated” warning in Magento 2 under PHP 8.1+ is caused by passing null values to string functions. The solution is to validate inputs or use null coalescing/type casting to ensure proper types. By applying these fixes across your custom modules and extensions, you can maintain a clean, warning‑free Magento environment.

Happy Coding & Stay Compatible!