str_replace()

A função PHP str_replace() substitui todas as ocorrências de uma string de busca por uma string de substituição. É útil para encontrar e trocar padrões específicos dentro de textos maiores. A seguir, abordamos a sintaxe, os principais recursos e exemplos de uso.

A função str_replace() é usada para substituir todas as ocorrências de uma string dentro de outra string. A sintaxe da função str_replace() é a seguinte:

A sintaxe PHP de str_replace()

str_replace($search, $replace, $subject, $count = null)

A função recebe três parâmetros obrigatórios e um opcional: $search, $replace, $subject e $count.

• $search: A string, ou array de strings, a ser buscada.
• $replace: A string, ou array de strings, a ser usada na substituição.
• $subject: A string, ou array de strings, dentro da qual buscar.
• $count (opcional): Uma variável passada por referência que recebe o número de substituições realizadas.

A função retorna o $subject modificado. A string original nunca é alterada diretamente, portanto é necessário capturar o valor de retorno. str_replace() é sensível a maiúsculas e minúsculas — "World" e "world" são tratados como strings diferentes. Se precisar ignorar a capitalização, use str_ireplace().

Um exemplo básico

Esta é a forma mais simples de usar a função str_replace() — substituindo uma palavra por outra:

Exemplo de PHP str_replace()

Neste exemplo, a variável string $string contém a frase "The quick brown fox jumps over the lazy dog." Substituímos a palavra "brown" por "red" passando "brown" como $search e "red" como $replace. A saída é:

The quick red fox jumps over the lazy dog.

Todas as ocorrências são substituídas — não apenas a primeira. Se a string de busca aparecer três vezes, todas as três serão substituídas em uma única chamada.

Substituindo múltiplas strings de uma vez

Quando $search e $replace são arrays, cada elemento de $search é substituído pelo elemento no mesmo índice em $replace. O quarto argumento opcional, $count, é passado por referência e recebe o número total de substituições:

Exemplo com arrays e $count

<?php
$search = ["brown", "fox"];
$replace = ["red", "bear"];
$subject = "The quick brown fox jumps over the lazy dog.";
$count = 0;
$result = str_replace($search, $replace, $subject, $count);
echo $result; // Output: The quick red bear jumps over the lazy dog.
echo "Replacements made: $count"; // Output: Replacements made: 2
?>

Se $replace for uma string única mas $search for um array, essa string única será usada para todas as correspondências:

<?php
$result = str_replace(["a", "e", "i"], "*", "education");
echo $result; // Output: *duc*t*on
?>

Um detalhe importante: substituições em cascata

As substituições por array são aplicadas em ordem, e cada uma é executada sobre o resultado da anterior. Isso significa que um valor recém-inserido pode ser correspondido novamente por um termo de busca posterior:

<?php
$count = 0;
$result = str_replace(["A", "B"], ["B", "C"], "A", $count);
echo $result;        // Output: C
echo "\n";
echo "Replacements: $count"; // Output: Replacements: 2
?>

Aqui "A" se torna "B" na primeira passagem, e então esse "B" se torna "C" na segunda passagem — portanto o resultado final é "C", com duas substituições contadas. Organize os pares de busca/substituição com cuidado para evitar isso, ou use strtr() quando precisar que cada par seja aplicado exatamente uma vez.

Quando usar str_replace()

• Use str_replace() para buscas e substituições literais rápidas quando você conhece o texto exato.
• Use str_ireplace() quando a correspondência deve ignorar maiúsculas e minúsculas.
• Use substr_replace() para substituir uma parte de uma string por posição em vez de por conteúdo.
• Use preg_replace() quando precisar de correspondência de padrões com expressões regulares.

A função str_replace() oferece uma forma direta e eficiente de pesquisar e substituir texto em PHP. Por funcionar com strings simples sem a sobrecarga de expressões regulares, é a ferramenta certa sempre que você estiver correspondendo texto literal e exato.

Prática