preg_match

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

preg_match — Виконує перевірку на відповідність регулярному виразу

Опис

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

Шукає у заданому тексті subject збіги з шаблоном pattern

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

pattern

Шуканий шаблон у вигляді рядка.

subject

Вхідний рядок.

matches

Якщо вказано додатковий параметр matches, він буде заповнений результатами пошуку. Елемент $matches[ ] міститиме частину рядка, що відповідає входу всього шаблону, $matches[ ] - частина рядка, що відповідає першій підмасці тощо.

flags

flags може бути комбінацією наступних прапорів:

PREG_OFFSET_CAPTURE

У випадку, якщо цей прапор вказано, для кожного знайденого підрядка буде вказано її позицію (в байтах) у вихідному рядку. Необхідно пам'ятати, що цей прапор змінює формат масиву, що повертається. matches масив, кожен елемент якого містить масив, що містить в індексі з номером знайдений підрядок, а зміщення цього підрядка у параметрі subject- в индексе

Loading...

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

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).

Loading...

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

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)*Сравните:
Loading...
Результат виконання наведеного прикладу:
Array
(
)
У той час як цей приклад
Loading...
виведе наступне:
Array
(
    [0] => Array
        (
            [0] => def
            [1] => 0
        )

)
Як альтернатива substr()(), используйте утверждение\G замість якоря ^ або модифікатор AОба они работают с параметромoffset

Значення, що повертаються

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

Увага

Ця функція може повертати як логічне значення **false**так і значення не типу boolean, яке наводиться до false. За більш детальною інформацією зверніться до розділу Логічний типИспользуйтеоператор === для перевірки значення, яке повертається цією функцією.

Помилки

Якщо переданий шаблон регулярного виразу не компілюється в допустимий регулярний вираз, видається помилка рівня E_WARNING

список змін

Версия	Опис
7.2.0	Тепер константа `PREG_UNMATCHED_AS_NULL` підтримується для параметра `$flags`

Приклади

Приклад #1 Пошук підрядки "php" у тексті

Loading...

Приклад #2 Пошук слова "web" у тексті

Loading...

Приклад #3 Вилучення домену з URL

Loading...

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

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

Приклад #4 Використання іменованих підмасок

Loading...

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

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