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