str_ireplace()

Функция str_ireplace() в PHP заменяет все вхождения искомой строки строкой замены, не учитывая регистр. Это нечувствительный к регистру аналог str_replace(): всё работает так же, только поиск не различает прописные и строчные буквы. Это делает str_ireplace() подходящим выбором, когда регистр целевого текста неизвестен или непоследователен — например, при очистке пользовательского ввода или нормализации тегов, которые могут встречаться как PHP, php или Php.

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

Синтаксис

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

Функция принимает три обязательных параметра и один необязательный:

• $search — значение (или массив значений) для поиска.
• $replace — значение (или массив значений), которым нужно заменить найденное.
• $subject — строка (или массив строк), в которой выполняется поиск.
• $count (необязательный) — переменная, передаваемая по ссылке, в которую записывается общее количество выполненных замен.

Функция возвращает изменённый $subject. Если $subject является массивом, возвращается массив с заменой, применённой к каждому элементу.

Базовый пример

Хотя мы ищем "FOX" в верхнем регистре, str_ireplace() игнорирует регистр и находит строчное "fox" в исходной строке. Результат:

The quick brown cat jumps over the lazy dog

При использовании стандартной чувствительной к регистру str_replace() тот же вызов не найдёт совпадений, и строка будет возвращена без изменений.

Использование массивов для поиска и замены

Когда $search и $replace оба являются массивами, каждое искомое значение сопоставляется со значением замены с тем же индексом. Это позволяет выполнять несколько подстановок за один вызов:

<?php
$search  = ["red", "GREEN", "Blue"];
$replace = ["crimson", "emerald", "navy"];
$subject = "Red, green and blue are colors.";

echo str_ireplace($search, $replace, $subject);
// crimson, emerald and navy are colors.
?>

Обратите внимание, что регистр элементов в $search не имеет значения — "GREEN" по-прежнему находит "green". Если в $replace элементов меньше, чем в $search, недостающие замены считаются пустыми строками (совпадения удаляются).

Когда $search является массивом, а $replace — одной строкой, эта строка заменяет каждое искомое значение:

<?php
echo str_ireplace(["cats", "dogs"], "pets", "I have CATS and Dogs.");
// I have pets and pets.
?>

Подсчёт замен с помощью $count

Передайте четвёртый аргумент по ссылке, чтобы узнать, сколько замен было выполнено:

<?php
$text   = "PHP is great. php is fun. PhP rocks.";
$result = str_ireplace("php", "PHP", $text, $count);

echo $result . "\n";       // PHP is great. PHP is fun. PHP rocks.
echo "Replacements: $count"; // Replacements: 3
?>

Все три варианта PHP, php и PhP совпадают, поэтому $count равен 3. Это удобно для валидации — например, чтобы проверить, встречалось ли запрещённое слово вообще.

Подводные камни

• Результат замены не сканируется повторно. str_ireplace() обрабатывает искомые значения слева направо и никогда не перепроверяет уже вставленный текст, поэтому она не может зациклиться. Однако порядок всё равно важен, когда одно искомое значение является подстрокой другого.
• Функция работает с байтами, а не с многобайтовыми символами. Для текста в кодировке UTF-8, где нечувствительность к регистру должна учитывать буквы с диакритическими знаками или не-латинские символы, str_ireplace() может вести себя неожиданно. Используйте функции PHP из группы mb_* или preg_replace() с модификатором i.
• Используйте str_replace(), когда регистр важен. Если требуется точное сопоставление с учётом регистра, воспользуйтесь str_replace() — она немного быстрее, поскольку пропускает этап приведения регистра.

Итог

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

Практика