PHP Manual
Функции PCRE
Выполняет поиск и замену по регулярному выражению

preg_replace

(PHP 4, PHP 5, PHP 7)

preg_replace — Выполняет поиск и замену по регулярному выражению

Описание

Выполняет поиск совпадений в строке subject с шаблоном pattern и заменяет их на replacement.

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

pattern

Искомый шаблон. Может быть как строкой, так и массивом строк.

Также доступны некоторые модификаторы PCRE.

replacement

Строка или массив строк для замены. Если этот параметр является строкой, а pattern является массивом, все шаблоны будут заменены этой строкой. Если и pattern и replacement являются массивами, каждый элемент pattern будет заменен соответствующим элементом из replacement. Если массив replacement содержит меньше элементов, чем массив pattern, то все лишние шаблоны из 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, а возвращаемое значение также будет являться массивом.

limit

Максимально возможное количество замен каждого шаблона для каждой строки subject. По умолчанию равно -1 (без ограничений).

count

Если указана, то эта переменная будет заполнена количеством произведенных замен.

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

preg_replace() возвращает массив, если параметр subject является массивом, иначе возвращается строка.

Если найдены совпадения, возвращается новая версия subject, иначе subject возвращается нетронутым, в случае ошибки возвращается null.

Ошибки

С версии PHP 5.5.0, если передается модификатор "\e", вызывается ошибка уровня E_DEPRECATED. С версии PHP 7.0.0 использование модификатора "\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, то вам необходимо прогнать через функцию ksort() оба массива перед использованием preg_replace().

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

Регулярные выражения PCRE
preg_quote() - Экранирует символы в регулярных выражениях
preg_filter() - Производит поиск и замену по регулярному выражению
preg_match() - Выполняет проверку на соответствие регулярному выражению
preg_replace_callback() - Выполняет поиск по регулярному выражению и замену с использованием callback-функции
preg_split() - Разбивает строку по регулярному выражению
preg_last_error() - Возвращает код ошибки выполнения последнего регулярного выражения PCRE