Функция preg_filter в PHP

Функция preg_filter в PHP выполняет поиск в строке (или массиве строк) текста, соответствующего регулярному выражению, и заменяет его. Её отличительная особенность состоит в том, что она возвращает только те элементы, в которых найдено совпадение — несовпадающие элементы отбрасываются. Это делает её идеальным инструментом для задач, где нужно выполнить поиск, замену и фильтрацию за один шаг.

Если вы использовали preg_replace, preg_filter покажется вам знакомой: синтаксис идентичен. Единственное поведенческое отличие — что происходит с несовпадающими аргументами — и делает preg_filter незаменимой в определённых ситуациях. Именно этому посвящена данная страница.

В этой статье мы рассмотрим синтаксис, параметры, отличия preg_filter от preg_replace, а также наиболее распространённые случаи применения с примерами, которые можно запустить.

Синтаксис и параметры

Синтаксис функции preg_filter выглядит следующим образом:

Синтаксис PHP preg_filter

preg_filter(pattern, replacement, subject [, limit [, count]])

Параметры:

• pattern: регулярное выражение, задающее текст для поиска.
• replacement: текст, которым будет заменён найденный фрагмент.
• subject: строка, в которой выполняется поиск и замена.
• limit (необязательный): максимальное количество замен для каждой строки. По умолчанию -1 (без ограничений).
• count (необязательный): переменная, передаваемая по ссылке, в которую будет записано общее количество выполненных замен.

Аргументы pattern, replacement и subject могут быть как одиночным значением, так и массивом — точно так же, как в preg_replace. Возвращаемое значение — строка, если subject является строкой, и массив, если subject является массивом.

preg_filter и preg_replace

Обе функции принимают одинаковые аргументы и выполняют одну и ту же работу по поиску и замене. Разница заключается в том, что они возвращают, когда аргумент не соответствует шаблону:

• preg_replace возвращает аргумент без изменений.
• preg_filter возвращает null для строкового аргумента и полностью исключает элемент из массива.

<?php
$input = ["123", "abc", "456"];

// preg_replace keeps every element, matched or not.
print_r(preg_replace("/\d+/", "[num]", $input));
// Array ( [0] => [num] [1] => abc [2] => [num] )

// preg_filter drops the non-matching "abc".
print_r(preg_filter("/\d+/", "[num]", $input));
// Array ( [0] => [num] [2] => [num] )
?>

Обратите внимание, что preg_filter сохраняет исходные ключи (0 и 2) — массив не переиндексируется.

Случаи применения

preg_filter наиболее полезна, когда нужно одновременно выполнить поиск, замену и фильтрацию. Типичные случаи применения:

• Фильтрация массивов: передайте массив строк и получите обратно только те элементы, которые совпали с шаблоном.
• Удаление HTML-тегов: очистка строк или массивов строк от тегов.
• Извлечение и переформатирование: замена найденного текста с одновременным отбрасыванием элементов, не представляющих интереса.

Пример: удаление HTML-тегов

В этом примере мы воспользуемся preg_filter для удаления HTML-тегов из строки:

Пример PHP preg_filter

В этом примере регулярное выражение /<[^>]+>/ используется для поиска всех HTML-тегов в строке $html. Параметр replacement задан как пустая строка, поэтому найденный текст удаляется. Результат сохраняется в переменной $text и выводится на экран.

Пример: фильтрация элементов массива

preg_filter особенно хороша при работе с массивами, поскольку автоматически удаляет несовпадающие элементы:

<?php
$items = ["apple", "banana", "apricot", "cherry"];
$filtered = preg_filter("/^a/", "A", $items);
print_r($filtered);
// Outputs:
// Array
// (
//     [0] => Apple
//     [2] => Apricot
// )
?>

В этом примере preg_filter заменяет начальную букву «a» на «A», но автоматически исключает «banana» и «cherry», поскольку они не соответствуют шаблону. Оставшиеся элементы сохраняют исходные ключи (0 и 2).

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

Необязательный пятый параметр заполняется по ссылке количеством выполненных замен. Это удобно для отчётности или для ветвления логики в зависимости от того, было ли найдено совпадение:

<?php
$subject = "Order #42 and order #7";
$result = preg_filter("/#(\d+)/", "[$1]", $subject, -1, $count);
echo $result . "\n";   // Order [42] and order [7]
echo $count . "\n";    // 2
?>

Здесь $1 в строке замены — это обратная ссылка на первую захватывающую группу. Было выполнено две замены, поэтому $count равен 2.

Заключение

preg_filter выполняет поиск и замену по регулярному выражению так же, как preg_replace, но отбрасывает аргументы, не соответствующие шаблону: возвращает null для строк и исключает несовпадающие элементы из массивов. Это делает её правильным выбором, когда фильтрация и замена должны выполняться за один шаг.

Чтобы глубже изучить инструментарий регулярных выражений PHP, обратитесь к preg_match для проверки одиночного совпадения, preg_match_all для поиска всех совпадений, preg_split для разбиения строк и preg_replace_callback, когда замену необходимо вычислять в коде.

Практика