PHP str_replace(): замена текста в строке

str_replace($search, $replace, $subject) возвращает копию $subject, в которой каждое вхождение $search заменено на $replace. str_replace('world', 'PHP', 'Hello world') возвращает "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

Функция возвращает новую строку и не меняет переданную переменную. Присваивайте результат, хоть бы и той же переменной: $text = str_replace(...).

Синтаксис

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

Каждый из первых трёх аргументов может быть строкой или массивом. Если $subject массив, замена выполняется для каждого элемента, и вы получаете массив с теми же ключами: str_replace('.txt', '.md', ['a.txt', 'b.txt']) возвращает ['a.md', 'b.md']. Поиск учитывает регистр и ищет обычный текст, а не шаблоны. Для шаблонов используйте preg_replace().

Замена нескольких строк сразу

Передайте массивы в $search и $replace. Первое искомое значение заменяется первой заменой, второе второй и так далее. Если $replace одна строка, ею заменяются все искомые значения, и это короткий способ удалить набор символов.

<?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";

Ловушка порядка и strtr()

С массивами str_replace() выполняет одну замену за другой по всей строке. Более поздний поиск может совпасть с текстом, который только что вставила более ранняя замена. strtr() с массивом заменяет всё за один проход, сначала пробует самые длинные ключи и никогда не трогает уже заменённый текст.

<?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";

Используйте strtr() для обмена значениями и для плейсхолдеров шаблона, которые могут встретиться в самих значениях.

Подсчёт замен

Четвёртый аргумент получает число выполненных замен. Передайте переменную, PHP запишет в неё результат.

<?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";

Замена без учёта регистра через str_ireplace

str_ireplace() принимает те же аргументы и при поиске не учитывает регистр. Замена вставляется ровно так, как вы её написали.

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

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

str_ireplace() приводит к одному регистру только ASCII-буквы. Для замены без учёта регистра букв с диакритикой или кириллицы используйте preg_replace() с модификаторами i и u.

Замена только первого вхождения

str_replace() всегда заменяет всё. Чтобы заменить только первое совпадение, найдите его через strpos() и вырежьте через 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";

Для последнего вхождения используйте strrpos() вместо strpos().

Удаление пробелов, переносов строк и других символов

Замена на пустую строку удаляет текст. Частая чистка убирает переносы строк или все пробелы, а в японском вводе часто встречаются полноширинные пробелы (　, U+3000), с которыми обычный поиск " " не совпадает.

<?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

Ставьте "\r\n" в массиве раньше "\n" и "\r", чтобы перенос строки Windows превращался в один пробел, а не в два.