preg_match()

Введение

preg_match() выполняет поиск по регулярному выражению в строке. Функция определяет, встречается ли шаблон PCRE в строке и, при необходимости, захватывает что именно совпало. Поиск останавливается после первого совпадения — если нужно найти все вхождения, используйте preg_match_all().

В этой главе рассматриваются сигнатура и возвращаемые значения функции, заполнение массива $matches, наиболее полезные флаги и типичные ошибки (ловушка 0 против false, якорение, разделители).

Синтаксис

preg_match(
    string $pattern,
    string $subject,
    array &$matches = null,
    int $flags = 0,
    int $offset = 0
): int|false

Возвращаемое значение: 1, если шаблон совпал; 0, если не совпал; или false при ошибке (неверный шаблон). Поскольку preg_match() возвращает не более 1, функция не сообщает, сколько совпадений существует — только то, что одно было найдено.

Базовый пример

Шаблон захватывает одно буквенное слово, за которым следуют пробел и ещё одно слово. При совпадении $matches[0] содержит полное совпадение (This is), а $matches[1] / $matches[2] — две захваченные группы (This и is).

Ловушка 0 против false

Очень распространённая ошибка — использование == для проверки результата. preg_match() возвращает 0 при «нет совпадения» и false только при ошибке, а 0 == false равно true в PHP. Всегда используйте строгий оператор сравнения:

<?php

$result = preg_match('/[0-9]+/', 'abc');

// Wrong: treats "no match" and "error" the same
if ($result == false) {
  echo "ambiguous\n";
}

// Right: distinguish the three outcomes
if ($result === false) {
  echo "Error in the pattern\n";
} elseif ($result === 0) {
  echo "No match\n";
} else {
  echo "Matched\n";
}

Это выведет ambiguous, а затем No match.

Именованные группы

Добавьте (?<name>...) в шаблон, и $matches будет содержать захваченные значения как по числовому индексу, так и по имени, что делает код читаемее при изменении порядка групп:

<?php

$date = '2026-06-21';
preg_match('/(?<year>\d{4})-(?<month>\d{2})-(?<day>\d{2})/', $date, $m);

echo $m['year'] . "\n";  // 2026
echo $m['month'] . "\n"; // 06
echo $m['day'];          // 21

Захват смещений с помощью PREG_OFFSET_CAPTURE

Передайте флаг PREG_OFFSET_CAPTURE, и каждый элемент в $matches станет парой [совпавший_текст, смещение_в_байтах], что позволяет определить где произошло совпадение:

<?php

preg_match('/world/', 'hello world', $m, PREG_OFFSET_CAPTURE);

echo $m[0][0] . "\n"; // world
echo $m[0][1];        // 6

Шаблоны без учёта регистра и с якорями

Модификаторы указываются после закрывающего разделителя. Модификатор i игнорирует регистр; ^ и $ привязывают совпадение к началу и концу строки, так что вся строка должна соответствовать шаблону:

<?php

var_dump(preg_match('/^hello$/i', 'HELLO')); // int(1)
var_dump(preg_match('/^hello$/i', 'hello!')); // int(0)

Когда использовать другие функции

• Все вхождения, а не только первое → preg_match_all().
• Поиск и замена → preg_replace().
• Разбиение строки по шаблону → preg_split(); для фиксированного разделителя быстрее использовать explode().
• Экранирование пользовательского ввода перед встраиванием в шаблон → preg_quote().
• Повторение синтаксиса PCRE → глава Регулярные выражения PHP.

Заключение

preg_match() — это основная функция для проверки, соответствует ли строка шаблону, и для извлечения захваченных групп. Помните о трёх возвращаемых значениях, используйте === для сравнения, чтобы избежать ловушки 0/false, и переходите к preg_match_all(), когда одного совпадения недостаточно.

Практика