(PHP 4, PHP 5, PHP 7, PHP 8)
str_replace — Substitui todas as ocorrências da string de pesquisa com a string de substituição
$search,$replace,$subject,&$count = null
Esta função retorna uma string ou um array com todas as ocorrências de
search em subject
substituídas com o valor informado em replace.
Para substituir texto baseado em um padrão que não seja uma string fixa, use preg_replace().
Se search e replace forem
arrays, então str_replace() pega um valor de cada array
e os usa para pesquisar e substituir em subject. Se
replace tiver menos valores do que
search, então uma string vazia é usada para o restante dos
valores de substituição. Se search for um array e
replace for uma string, então esta string de substituição é
usada para cada valor de search. O contrário não
faria sentido, contudo.
Se search ou replace
forem arrays, seus elementos são processados do primeiro ao último.
searchO valor sendo pesquisado, também conhecido como agulha. Um array pode ser usado para designar múltiplas agulhas.
replace
O valor de substituição que será usado no lugar dos valores de search
encontrados. Um array pode ser usado para deignar múltiplas substituições.
subjectA string ou array sendo pesquisado ou substituído, também conhecido como o palheiro.
Se subject for um array, então a pesquisa e
a substituição são executadas com cada entrada de
subject, e o valor de retorno é um array
também.
countSe passado, será definido para o número de substituições realizadas.
Esta função retorna uma string ou um array com os valores substituídos.
Exemplo #1 Exemplos básicos de str_replace()
<?php
// Produz: <body text='black'>
$bodytag = str_replace("%body%", "black", "<body text='%body%'>");
echo $bodytag, PHP_EOL;
// Produz: Hll Wrld f PHP
$vowels = array("a", "e", "i", "o", "u", "A", "E", "I", "O", "U");
$onlyconsonants = str_replace($vowels, "", "Hello World of PHP");
echo $onlyconsonants, PHP_EOL;
// Produz: Você deveria comer pizza, cerveja e sorvete todos os dias.
$frase = "Você deveria comer frutas, vegetais, e fibra todos os dias.";
$saudavel = array("frutas", "vegetais", "fibra");
$saboroso = array("pizza", "cerveja", "sorvete");
$novafrase = str_replace($saudavel, $saboroso, $frase);
echo $novafrase, PHP_EOL;
// Produz: 2
$str = str_replace("ll", "", "good golly miss molly!", $count);
echo $count, PHP_EOL;
?>
Exemplo #2 Exemplos de armadilhas potenciais de str_replace()
<?php
// Ordem da substituição
$str = "Linha 1\nLinha 2\rLinha 3\r\nLinha 4\n";
$order = array("\r\n", "\n", "\r");
$replace = '<br />';
// Processa \r\n primeiro para que não sejam substituídos duas vezes.
$newstr = str_replace($order, $replace, $str);
echo $newstr, PHP_EOL;
// Mostra F porque A é substituído por B, depois B é substituído por C, e assim por diante...
// Finalmente E é substituído por F, porque a substituição é feita da esquerda para a direita.
$search = array('A', 'B', 'C', 'D', 'E');
$replace = array('B', 'C', 'D', 'E', 'F');
$subject = 'A';
echo str_replace($search, $replace, $subject), PHP_EOL;
// Mostra: apearpearle pear
// Pelo memos motivo mencionado acima
$letters = array('a', 'p');
$fruit = array('apple', 'pear');
$text = 'a p';
$output = str_replace($letters, $fruit, $text);
echo $output, PHP_EOL;
?>Nota: Esta função é compatível com dados binários.
Como str_replace() substitui da esquerda para a direita, ela pode substituir um valor previamente inserido quando estiver fazendo múltiplas substituições. Veja também os exemplos neste documento.
Nota:
Esta função é sensível a maiúsculas/minúsculas. Use str_ireplace() para substituição insensível a maiúsculas/minúsculas.