PHP str_replace() Function: Usage and Examples

When you need to replace all literal occurrences of a substring, it helps to understand both the normal result and what changes with different inputs. This guide focuses on practical examples rather than repeating PHP background material.

str_replace provides the behavior described below. Replacements are case-sensitive and performed sequentially if search is an array.

What Is str_replace in PHP?

Replace all literal occurrences of a substring. Replacements are case-sensitive and performed sequentially if search is an array.

Its syntax is:

str_replace(array|string $search, array|string $replace, array|string $subject, &$count = ...): array|string

Parameters and return value: Read the argument names and optional values in the signature above. Methods use an existing object, while stand-alone functions take direct arguments. The examples demonstrate the relevant arguments and the value returned or the object modified.

Important: Replacing text is not escaping it for HTML or SQL; choose destination-specific encoding.

Example 1: Basic Usage

This first example demonstrates how to replace all literal occurrences of a substring with a small input.

<?php

echo str_replace("draft", "published", "draft document");

Output:

published document

The example uses the simplest useful form. Replacements are case-sensitive and performed sequentially if search is an array. The output may depend on the active ICU locale, PHP configuration, or input supplied to the function.

Example 2: Another Case

Here the input or option changes, making it easier to see where the behavior differs. Replacing text is not escaping it for HTML or SQL; choose destination-specific encoding.

<?php

$replacementCount = 0;
echo str_replace("cat", "dog", "cat cat", $replacementCount);
echo " / " . $replacementCount;

Output:

dog dog / 2

Compare the result to the first example. str_ireplace() ignores case; preg_replace() evaluates a regex.

Practical Example: Applying the Function

This standalone example shows how the same operation fits into a small application task.

<?php

$messageTemplate = "Hello {name}, order {order} is ready.";
$message = str_replace(["{name}", "{order}"], ["Maya", "A104"], $messageTemplate);
echo $message;

Output:

Hello Maya, order A104 is ready.

The example keeps the operation visible and gives you a starting point for using it in an application. Replacing text is not escaping it for HTML or SQL; choose destination-specific encoding.

Important Behavior and Edge Cases

• Core behavior: Replacements are case-sensitive and performed sequentially if search is an array.
• Return value: Check the result separately from changes to passed-in arrays, iterators, or object state.
• Data constraints: Replacing text is not escaping it for HTML or SQL; choose destination-specific encoding.
• Environment: Run this example under a PHP version supporting the API; check results and exceptions before using them.

Comparison With Related Functions

Common Beginner Mistakes

Key Takeaways

• str_replace helps you replace all literal occurrences of a substring.
• Replacements are case-sensitive and performed sequentially if search is an array.
• Replacing text is not escaping it for HTML or SQL; choose destination-specific encoding.
• str_ireplace() ignores case; preg_replace() evaluates a regex.

str_replace is useful when you need to replace all literal occurrences of a substring. Start with the small examples, then adapt the practical example while respecting its input and environment requirements.