Строка или массив строк, в которых функция будет искать
и заменять совпадения.
Эта строка заменит каждую подстроку входной строки,
которая совпала с шаблоном, если в этот параметр передали строку,
а в параметр 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 помогает понять, как интерпретатор будет видеть строку.