(PHP 4, PHP 5, PHP 7, PHP 8)
preg_replace — Выполняет поиск и замену по регулярному выражению
$pattern
,$replacement
,$subject
,$limit
= -1,&$count
= null
Функция ищет в строке subject
совпадения с шаблоном pattern
и заменяет совпадения на значение replacement
.
Вместо этой функции обращаются к функциям str_replace() или str_ireplace(), когда требуется найти соответствие точной строке, а не шаблону.
pattern
Искомый шаблон: строка или массив строк.
В шаблоне также указывают модификаторы модуля PCRE .
replacement
Строка или массив строк, в которых функция будет искать и заменять совпадения. Эта строка заменит каждую подстроку входной строки, которая совпала с шаблоном, если в этот параметр передали строку, а в параметр pattern
— массив. Функция заменит каждую подстроку, которая совпала c шаблоном в массиве pattern
, на значение replacement
с тем же смещением внутреннего указателя массива, что и у шаблона, если и параметр pattern
, и параметр replacement
— массивы. Функция заменит на пустую строку каждую подстроку, которая совпала с лишним шаблоном в массиве pattern
, если массив replacement
содержит меньше элементов, чем массив pattern
.
В параметре replacement
разрешается указывать ссылки вида \n
или $n
, причём лучше предпочесть последний вариант. Каждую такую ссылку функция заменит на подстроку, которую захватил n-й подшаблон в круглых скобках. Номер группы n принимает значения от 0 до 99, причём ссылки \0
или $0
соответствует вхождению всего шаблона. Открывающие подшаблон скобки нумеруются слева направо, начиная с единицы, и указывают на номер подшаблона захвата. Обратите внимание, в отдельных ситуациях обратные слеши в строковых (string) литералах требуют экранирования.
Когда при работе с шаблоном замены за обратной ссылкой сразу идёт другое число (то есть буквальное число идёт сразу после подстроки, которая совпала с шаблоном), для ссылки на подшаблон нельзя использовать знакомую нотацию вида \1
. Например, запись \11
собьёт функцию preg_replace() с толку, поскольку функция не знает, требуется ли выбрать первую обратную ссылку \1
, за которой идёт буквальная цифра 1
, или требуется выбрать одиннадцатую обратную ссылку \11
, за которой ничего не идёт. Решение состоит в том, чтобы использовать конструкцию ${1}1
, которая создаёт изолированную обратную ссылку $1
, а число 1
оставляет литералом.
Если в шаблоне указали устаревший модификатор e
, функция заэкранирует в строках, которыми замещаются обратные ссылки, отдельные символы: '
, "
, \
и NULL. Это сделали, чтобы гарантировать отсутствие синтаксических ошибок при записи обратных ссылок в одинарных или двойных кавычках: 'strlen(\'$1\')+strlen("$2")'
. Знание синтаксиса записи строк в PHP помогает понять, как интерпретатор будет видеть строку.
subject
Строка или массив строк для поиска и замены.
Функция найдёт и заменит каждый элемент массива subject
, а затем вернёт массив, если в параметр subject
передали массив.
Функция сохранит ключи в массиве с результатами, если в параметр subject
передали ассоциативный массив.
limit
Максимальное количество замен каждого шаблона для каждой строки subject
. Значение по умолчанию равно -1
— не ограничивать количество замен.
count
Функция заполнит эту переменную количеством замен, которые она выполнила, если переменную указали.
Функция preg_replace() возвращает массив, если в параметр subject
передали массив, иначе возвращается строка.
Функция возвращает новую версию значения subject
, если нашла совпадения, иначе значение subject
возвращается нетронутым. Функция возвращает null
, если возникла ошибка.
Функция выдаёт ошибку уровня E_WARNING
, когда в шаблоне указывают модификатор \e.
Если передали шаблон регулярного выражения, который не компилируется в допустимое регулярное выражение, выдаётся ошибка уровня E_WARNING
.
Пример #1 Пример обратных ссылок, за которыми следуют числовые литералы
<?php
$string = 'April 15, 2003';
$pattern = '/(\w+) (\d+), (\d+)/i';
$replacement = '${1}1,$3';
echo preg_replace($pattern, $replacement, $string);
?>
Результат выполнения приведённого примера:
April1,2003
Пример #2 Пример обработки функцией preg_replace() индексных массивов
<?php
$string = 'The quick brown fox jumps over the lazy dog.';
$patterns = array();
$patterns[0] = '/quick/';
$patterns[1] = '/brown/';
$patterns[2] = '/fox/';
$replacements = array();
$replacements[2] = 'bear';
$replacements[1] = 'black';
$replacements[0] = 'slow';
echo preg_replace($patterns, $replacements, $string);
?>
Результат выполнения приведённого примера:
The bear black slow jumps over the lazy dog.
После сортировки шаблонов и замен по ключам получаем правильный результат:
<?php
ksort($patterns);
ksort($replacements);
echo preg_replace($patterns, $replacements, $string);
?>
Результат выполнения приведённого примера:
The slow black bear jumps over the lazy dog.
Пример #3 Пример замены ряда значений по набору шаблонов
<?php
$patterns = array(
'/(19|20)(\d{2})-(\d{1,2})-(\d{1,2})/',
'/^\s*{(\w+)}\s*=/'
);
$replace = array('\3/\4/\1\2', '$\1 =');
echo preg_replace($patterns, $replace, '{startDate} = 1999-5-27');
?>
Результат выполнения приведённого примера:
$startDate = 5/27/1999
Пример #4 Пример удаления пробелов
В этом примере функция удаляет из строки лишние пробелы.
<?php
$str = 'foo o';
$str = preg_replace('/\s\s+/', ' ', $str);
// Теперь строка будет выглядеть вот так: 'foo o'
echo $str;
?>
Пример #5 Пример с параметром count
<?php
$count = 0;
echo preg_replace(array('/\d/', '/\s/'), '*', 'xp 4 to', -1 , $count);
echo $count; // 3
?>
Результат выполнения приведённого примера:
xp***to 3
Замечание:
Функция обрабатывает ключи в том порядке, в котором ключи появляются в массиве, когда в параметры
pattern
иreplacement
передают массивы. Порядок ключей в этих массивах — не то же, что порядок числовых индексов. Если индексы требуются, чтобы определить, какой шаблонpattern
требуется заменить какой заменойreplacement
, перед тем как вызывать функцию preg_replace(), на каждом массиве вызывают функцию ksort().
Замечание:
Функция применяет правила сопоставления последовательно, если и в параметр
pattern
, и в параметрreplacement
передали массив. То есть, вторая параpattern
/replacement
будет работать со строкой, которую функция получила в результате обработки первой парыpattern
/replacement
, а не с исходной строкой. Когда требуется сымитировать параллельные замены, например, чтобы поменять два значения местами, один шаблон заменяют промежуточным заполнителем, а затем в следующей паре заменяют этот промежуточный заполнитель нужной заменой.<?php
$p = array('/a/', '/b/', '/c/');
$r = array('b', 'c', 'd');
print_r(preg_replace($p, $r, 'a'));
// Выводит: d
?>