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

# preg_match

(PHP 4, PHP 5, PHP 7, PHP 8)

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

### Описание

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

Функция ищет в строке `subject` совпадения с шаблоном регулярного выражения `pattern`.

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

`pattern`

  Искомый шаблон в виде строки.

`subject`

  Входная строка.

`matches`

  Функция заполнит параметр `matches` результатами поиска, если в функцию передали аргумент для этого параметра. Элемент $matches[0] будет содержать текст, который соответствует вхождению полного шаблона, элемент $matches[1] будет содержать текст, который соответствует первому подшаблону, который захватили круглые скобки, и так далее.

`flags`

  Параметр `flags` принимает комбинацию следующих флагов:

  `PREG_OFFSET_CAPTURE`

    Если этот флаг указали, для каждой найденной подстроки будет указана её позиция (в байтах) в исходной строке. Необходимо помнить, что этот флаг меняет формат возвращаемого массива `matches` на массив, каждый элемент которого содержит массив, который содержит в индексе с номером `0` найденную подстроку, а смещение этой подстроки в параметре `subject` — в индексе `1`.

        <?php

        preg_match('/(foo)(bar)(baz)/', 'foobarbaz', $matches, PREG_OFFSET_CAPTURE);
        print_r($matches);

        ?>

    Результат выполнения приведённого примера:

        Array
        (
            [0] => Array
                (
                    [0] => foobarbaz
                    [1] => 0
                )

            [1] => Array
                (
                    [0] => foo
                    [1] => 0
                )

            [2] => Array
                (
                    [0] => bar
                    [1] => 3
                )

            [3] => Array
                (
                    [0] => baz
                    [1] => 6
                )

        )

  `PREG_UNMATCHED_AS_NULL`

    Если этот флаг установили, функция заполнит несовпадающие подшаблоны значениями `null`; в противном случае они отображаются как пустые строки (string).

        <?php

        preg_match('/(a)(b)*(c)/', 'ac', $matches);
        var_dump($matches);

        preg_match('/(a)(b)*(c)/', 'ac', $matches, PREG_UNMATCHED_AS_NULL);
        var_dump($matches);

        ?>

    Результат выполнения приведённого примера:

        array(4) {
          [0]=>
          string(2) "ac"
          [1]=>
          string(1) "a"
          [2]=>
          string(0) ""
          [3]=>
          string(1) "c"
        }
        array(4) {
          [0]=>
          string(2) "ac"
          [1]=>
          string(1) "a"
          [2]=>
          NULL
          [3]=>
          string(1) "c"
        }

`offset`

  Обычно поиск идёт с начала строки слева направо. Можно установить дополнительный параметр `offset`, чтобы указать альтернативную начальную позиции для поиска (в байтах).

  > Замечание:

  > Поведение параметра `offset` не эквивалентно замене сопоставляемой строки выражением `substr($subject, $offset)` при вызове функции preg_match(), поскольку шаблон `pattern` может содержать условия наподобие ^, $ или (?<=x). Сравните:

  >     <?php

  >     $subject = "abcdef";
  >     $pattern = '/^def/';
  >     preg_match($pattern, $subject, $matches, PREG_OFFSET_CAPTURE, 3);
  >     print_r($matches);

  >     ?>

  > Результат выполнения приведённого примера:

  >     Array
  >     (
  >     )

  > Тогда как этот пример

  >     <?php

  >     $subject = "abcdef";
  >     $pattern = '/^def/';
  >     preg_match($pattern, substr($subject,3), $matches, PREG_OFFSET_CAPTURE);
  >     print_r($matches);

  >     ?>

  > выведет следующее:

  >     Array
  >     (
  >         [0] => Array
  >             (
  >                 [0] => def
  >                 [1] => 0
  >             )

  >     )

  > В качестве альтернативы функции substr()() вместо якоря `^` записывают утверждение `\G` или модификатор `A`. Они оба работают с параметром `offset`.

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

Функция preg_match() возвращает 1, если параметр `pattern` соответствует переданному параметру `subject`, 0, если не соответствует, или `false`, если возникла ошибка.

Внимание

Функция возвращает как логическое значение `false`, так и нелогическое значение, которое приводится к `false`. Прочитайте раздел «Логический тип», чтобы получить дополнительную информацию. Используйте оператор === для проверки значения, которое возвращает функция.

### Ошибки

Если передали шаблон регулярного выражения, который не компилируется в допустимое регулярное выражение, выдаётся ошибка уровня `E_WARNING`.

### Список изменений

Версия | Описание
--- | ---
7.2.0 | Теперь константа `PREG_UNMATCHED_AS_NULL` поддерживается для параметра `$flags`.

### Примеры

Пример #1 Поиск подстроки "php" в тексте

    <?php

    // Символ "i" после закрывающего разделителя шаблона означает
    // регистронезависимый поиск
    if (preg_match("/php/i", "PHP is the web scripting language of choice.")) {
        echo "Вхождение найдено.";
    } else {
        echo "Вхождение не найдено.";
    }

    ?>

Пример #2 Поиск слова "web" в тексте

    <?php

    /* Специальная последовательность \b в шаблоне означает границу слова,
       следовательно, только изолированное вхождение слова 'web' будет
       соответствовать маске, в отличие от "webbing" или "cobweb" */
    if (preg_match("/\bweb\b/i", "PHP is the web scripting language of choice.")) {
        echo "Вхождение найдено.";
    } else {
        echo "Вхождение не найдено.";
    }

    echo "\n";

    if (preg_match("/\bweb\b/i", "PHP is the website scripting language of choice.")) {
        echo "Вхождение найдено.";
    } else {
        echo "Вхождение не найдено.";
    }

    ?>

Пример #3 Извлечение доменного имени из URL

    <?php

    // Извлекаем имя хоста из URL
    preg_match('@^(?:http://)?([^/]+)@i',
        "http://www.php.net/index.html", $matches);
    $host = $matches[1];

    // Извлекаем две последние части имени хоста
    preg_match('/[^.]+\.[^.]+$/', $host, $matches);
    echo "доменное имя: {$matches[0]}\n";

    ?>

Результат выполнения приведённого примера:

    доменное имя: php.net

Пример #4 Использование именованных подмасок

    <?php

    $str = 'foobar: 2008';

    preg_match('/(?P<name>\w+): (?P<digit>\d+)/', $str, $matches);

    /* Альтернативный вариант */
    // preg_match('/(?<name>\w+): (?<digit>\d+)/', $str, $matches);

    print_r($matches);

    ?>

Результат выполнения приведённого примера:

    Array
    (
        [0] => foobar: 2008
        [name] => foobar
        [1] => foobar
        [digit] => 2008
        [2] => 2008
    )

### Примечания

Подсказка

Не пользуйтесь функцией preg_match(), если необходимо проверить наличие подстроки в заданной строке. Вызывайте для этого функцию strpos(), поскольку она выполнят эту задачу гораздо быстрее.

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

- "Регулярные выражения PCRE"
- preg_quote() - Экранирует символы в регулярных выражениях
- preg_match_all() - Выполняет глобальный поиск шаблона в строке
- preg_replace() - Выполняет поиск и замену по регулярному выражению
- preg_split() - Разбивает строку по регулярному выражению
- preg_last_error() - Возвращает код ошибки выполнения последнего регулярного выражения PCRE
- preg_last_error_msg() - Возвращает сообщение об ошибке последней запущенной функции PCRE

`↑` and `↓` to navigate • `Enter` to select • `Esc` to close • `/` to open