preg_match

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

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.