str_replace
(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
Descrição
array|string
$search,array|string
$replace,string|array
$subject,int
&$count = null): string|array
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().
Parâmetros
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.
search-
O 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
searchencontrados. Um array pode ser usado para deignar múltiplas substituições. subject-
A string ou array sendo pesquisado ou substituído, também conhecido como o palheiro.
Se
subjectfor um array, então a pesquisa e a substituição são executadas com cada entrada desubject, e o valor de retorno é um array também. count-
Se passado, será definido para o número de substituições realizadas.
Valor Retornado
Esta função retorna uma string ou um array com os valores substituídos.
Exemplos
Example #1 Exemplos básicos de str_replace()
<?php
// Produz: <body text='black'>
$bodytag = str_replace("%body%", "black", "<body text='%body%'>");
// 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");
// 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);
// Produz: 2
$str = str_replace("ll", "", "good golly miss molly!", $count);
echo $count;
?>
Example #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);
// 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);
// 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;
?>Notas
Note: Esta função é compatível com dados binários.
Armadilha da ordem de substituição
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.
Note:
Esta função é sensível a maiúsculas/minúsculas. Use str_ireplace() para substituição insensível a maiúsculas/minúsculas.
Veja Também
- str_ireplace() - Versão insensível a maiúsculas/minúsculas de str_replace
- substr_replace() - Substitui o texto dentro de uma parte de uma string
- preg_replace() - Realiza uma pesquisa por uma expressão regular e substitui
- strtr() - Traduz caracteres ou substitui substrings