str_replace

(PHP 4, PHP 5, PHP 7, PHP 8)

str_replace — Заменяет вхождения строки поиска строкой замены

Описание

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

Функция возвращает строку или массив, в котором заменила вхождения search в subject значением replace.

Замену текста на основе шаблона, а не фиксированной строки, выполняют функцией preg_replace().

Список параметров

Если параметры search и replace — массивы, функция str_replace() возьмёт значение из каждого массива для поиска и замены во входной строке subject. Если в массиве replace значений меньше, чем в массиве search, функция заменит остальные значения пустой строкой. Функция заменит строкой замены каждое значение массива search, если параметр search — массив, а параметр replace — строка. Обратное не имело бы смысла.

Если параметры search или replace — массивы, функция обработает элементы массивов от первого к последнему.

search

Искомое значение, которое знают также как needle: иголку, которую требуется найти в стоге сена. В параметр передают массив значений, когда требуется найти несколько «иголок» одновременно.

replace

Значение замены, которым функция заменит значения search, которые найдёт. В параметр передают массив значений, когда требуется выполнить несколько замен.

subject

Строка или массив для поиска и замены, которые знают также как haystack: стог сена, в котором требуется найти иголку.

Функция выполнит поиск и замену с каждым элементом массива subject, если параметр subject — массив, и результат тоже будет массивом.

count

Функция установит для этого параметра количество замен, если аргумент передали.

Возвращаемые значения

Функция возвращает строку или массив с заменёнными значениями.

Примеры

Пример #1 Примеры использования функции str_replace()

<?php

// Даёт: <body text='black'>
$bodytag = str_replace("%body%", "black", "<body text='%body%'>");
echo $bodytag, PHP_EOL;

// Даёт: 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;

// Даёт: You should eat pizza, beer, and ice cream every day
$phrase  = "You should eat fruits, vegetables, and fiber every day.";
$healthy = array("fruits", "vegetables", "fiber");
$yummy   = array("pizza", "beer", "ice cream");

$newphrase = str_replace($healthy, $yummy, $phrase);
echo $newphrase, PHP_EOL;

// Даёт: 2
$str = str_replace("ll", "", "good golly miss molly!", $count);
echo $count, PHP_EOL;

?>

Пример #2 Примеры неочевидного поведения функции str_replace()

<?php

// Порядок замены
$str     = "Строка 1\nСтрока 2\rСтрока 3\r\nСтрока 4\n";
$order   = array("\r\n", "\n", "\r");
$replace = '<br />';

// Сначала обработаем последовательности символов \r\n, чтобы значения замены не появились дважды
echo $newstr = str_replace($order, $replace, $str);
echo $newstr, PHP_EOL;

// Выводит F, поскольку A заменяется на B, затем B на C и так далее...
// Наконец E заменяется на F, поскольку функция заменяет значения слева направо
$search  = array('A', 'B', 'C', 'D', 'E');
$replace = array('B', 'C', 'D', 'E', 'F');
$subject = 'A';
echo str_replace($search, $replace, $subject), PHP_EOL;

// Выводит: яблорехкорех орех по той же причине
$letters = array('я', 'о');
$fruit   = array('яблоко', 'орех');
$text    = 'я о';
$output  = str_replace($letters, $fruit, $text);
echo $output, PHP_EOL;

?>

Примечания

Замечание: Функция безопасна для обработки данных в двоичной форме.

Предостережение

Замечание о порядке замены

При множественных заменах функция str_replace() заменит значение, которое вставила на предыдущем шаге, очередным значением, поскольку заменяет значения слева направо. Примеры на этой странице показывают порядок замены.

Замечание:
Функция чувствительна к регистру. Замену без учёта регистра выполняет функция str_ireplace().

Смотрите также

str_ireplace() - Регистронезависимый вариант функции str_replace
substr_replace() - Заменяет часть строки
preg_replace() - Выполняет поиск и замену по регулярному выражению
strtr() - Заменяет символы или подстроки