PHP str_replace(): substituir texto numa string

str_replace($search, $replace, $subject) retorna uma cópia de $subject com cada ocorrência de $search substituída por $replace. str_replace('world', 'PHP', 'Hello world') retorna "Hello PHP".

<?php
$text = 'I like cats. cats are great.';

$new = str_replace('cats', 'dogs', $text);

echo $new, "\n";
echo $text, "\n";   // the original is unchanged

A função retorna a nova string; ela não altera a variável que você passa. Atribua o resultado, mesmo que à mesma variável: $text = str_replace(...).

Sintaxe

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

Cada um dos três primeiros argumentos pode ser uma string ou um array. Se $subject for um array, a substituição roda em cada elemento e você recebe um array de volta com as mesmas chaves: str_replace('.txt', '.md', ['a.txt', 'b.txt']) retorna ['a.md', 'b.md']. A busca diferencia maiúsculas e minúsculas e procura texto simples, não padrões. Para padrões, use preg_replace().

Substituir várias strings de uma vez

Passe arrays para $search e $replace. O primeiro valor de busca é substituído pela primeira substituição, o segundo pela segunda, e assim por diante. Se $replace for uma única string, todos os valores de busca são substituídos por ela, que é o jeito curto de remover um conjunto de caracteres.

<?php
$template = 'Hello {name}, your order {id} has shipped.';

echo str_replace(['{name}', '{id}'], ['Ada', '#1042'], $template), "\n";

// One replacement for every search value: remove punctuation
echo str_replace(['.', ',', '!', '?'], '', 'Hi, there! Ready? Yes.'), "\n";

// Fewer replacements than searches: the missing ones are ""
echo str_replace(['a', 'b', 'c'], ['1'], 'abcabc'), "\n";

A armadilha da ordem e o strtr()

Com arrays, o str_replace() executa uma substituição depois da outra sobre a string inteira. Uma busca posterior pode bater com um texto que uma substituição anterior acabou de inserir. O strtr() com um array substitui tudo numa única passada, tenta as chaves mais longas primeiro e nunca mexe num texto que já substituiu.

<?php
$s = 'apple banana';

// apple -> banana, then every banana (including the new one) -> cherry
echo str_replace(['apple', 'banana'], ['banana', 'cherry'], $s), "\n";

// One pass: each original word is replaced once
echo strtr($s, ['apple' => 'banana', 'banana' => 'cherry']), "\n";

Use strtr() para trocas e para marcadores de template que podem aparecer nos valores.

Contar as substituições

O quarto argumento é preenchido com o número de substituições feitas. Passe uma variável; o PHP escreve nela.

<?php
$text = 'one fish, two fish, red fish, blue fish';

$result = str_replace('fish', 'cat', $text, $count);

echo $result, "\n";
echo "Replaced $count times\n";

Substituir sem diferenciar maiúsculas com str_ireplace

O str_ireplace() recebe os mesmos argumentos e ignora maiúsculas e minúsculas ao procurar. A substituição é inserida exatamente como você a escreveu.

<?php
$text = 'PHP, php and Php';

echo str_replace('php', 'Python', $text), "\n";
echo str_ireplace('php', 'Python', $text), "\n";

O str_ireplace() só iguala letras ASCII. Para substituir sem diferenciar maiúsculas em letras acentuadas ou cirílicas, use preg_replace() com os modificadores i e u.

Substituir só a primeira ocorrência

O str_replace() sempre substitui tudo. Para substituir só a primeira correspondência, encontre-a com strpos() e recorte-a com substr_replace():

<?php
function replaceFirst(string $search, string $replace, string $subject): string
{
    $pos = strpos($subject, $search);
    if ($pos === false) {
        return $subject;
    }
    return substr_replace($subject, $replace, $pos, strlen($search));
}

echo replaceFirst('a', 'A', 'banana'), "\n";

// The same with a regex and a limit of 1
echo preg_replace('/' . preg_quote('a', '/') . '/', 'A', 'banana', 1), "\n";

Para a última ocorrência, use strrpos() no lugar de strpos().

Remover espaços, quebras de linha e outros caracteres

Substituir por uma string vazia remove o texto. Uma limpeza comum remove quebras de linha ou todos os espaços, e entradas em japonês muitas vezes contêm espaços de largura total (　, U+3000) que uma busca por " " normal não encontra.

<?php
$text = "line one\r\nline two\nline three";
echo str_replace(["\r\n", "\n", "\r"], ' ', $text), "\n";

$phone = '090 1234 5678';
echo str_replace(' ', '', $phone), "\n";

$name = '山田　太郎';
echo str_replace('　', ' ', $name), "\n";   // full-width space to normal space

Coloque "\r\n" antes de "\n" e "\r" no array, para que uma quebra de linha do Windows vire um espaço e não dois.