Выполняет глобальный поиск шаблона в строке

Описание

int preg_match_all ( string $pattern , string $subject [, array &$matches [, int $flags = PREG_PATTERN_ORDER [, int $offset = 0 ]]] )

Ищет в строке subject все совпадения с шаблоном pattern и помещает результат в массив matches в порядке, определяемом комбинацией флагов flags.

После нахождения первого соответствия последующие поиски будут осуществляться не с начала строки, а от конца последнего найденного вхождения.

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

pattern

Искомый шаблон, строка.

subject

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

matches

Параметр flags регулирует порядок вывода совпадений в возвращаемом многомерном массиве.

flags

Может быть комбинацией следующих флагов (необходимо понимать, что использование PREG_PATTERN_ORDER одновременно с PREG_SET_ORDER бессмысленно):

PREG_PATTERN_ORDER

Упорядочивает результаты так, что элемент $matches[0] содержит массив полных вхождений шаблона, элемент $matches[1] содержит массив вхождений первой подмаски, и так далее.


<?php
preg_match_all("|<[^>]+>(.*)</[^>]+>|U",
    "<b>пример: </b><div align=left>это тест</div>",
    $out, PREG_PATTERN_ORDER);
echo $out[0][0] . ", " . $out[0][1] . "\n";
echo $out[1][0] . ", " . $out[1][1] . "\n";
?>

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

<b>пример: </b>, <div align=left>это тест</div>
пример: , это тест

Таким образом, $out[0] содержит массив полных вхождений шаблона, а $out[1] содержит массив подстрок, содержащихся в тегах.

PREG_SET_ORDER

Упорядочивает результаты так, что элемент $matches[0] содержит первый набор вхождений, элемент $matches[1] содержит второй набор вхождений, и так далее.


<?php
preg_match_all("|<[^>]+>(.*)</[^>]+>|U",
    "<b>пример: </b><div align=\"left\">это тест</div>",
    $out, PREG_SET_ORDER);
echo $out[0][0] . ", " . $out[0][1] . "\n";
echo $out[1][0] . ", " . $out[1][1] . "\n";
?>

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

<b>пример: </b>, пример:
<div align="left">это тест</div>, это тест

PREG_OFFSET_CAPTURE

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

В случае если флаги не были указаны, по умолчанию используется PREG_PATTERN_ORDER.

offset

Обычно поиск осуществляется слева направо, с начала строки. Дополнительный параметр offset может быть использован для указания альтернативной начальной позиции для поиска.

Замечание:
Использование параметра offset не эквивалентно замене сопоставляемой строки выражением substr($subject, $offset) при вызове функции preg_match_all(), поскольку шаблон pattern может содержать такие условия как ^, $ или (?<=x). Вы можете найти соответствующие примеры в описании функции preg_match().

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

Возвращает количество найденных вхождений шаблона (которое может быть и нулем) либо FALSE, если во время выполнения возникли какие-либо ошибки.

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

Версия	Описание
5.4.0	Параметр `matches` стал необязательным.
5.3.6	Возвращает `FALSE` если `offset` больше чем длина `subject`.
5.2.2	Именованные подмаски теперь принимают синтаксис (?<name>) и (?'name'), также как и (?P<name>). Предыдущие версии принимали только (?P<name>).
4.3.3	Добавлен параметр `offset`
4.3.0	Добавлен флаг `PREG_OFFSET_CAPTURE`

Примеры

Пример #1 Получение всех телефонных номеров из текста.


<?php
preg_match_all("/\(?  (\d{3})?  \)?  (?(1)  [\-\s] ) \d{3}-\d{4}/x",
                "Звоните 555-1212 или 1-800-555-1212", $phones);
?>

Пример #2 Жадный поиск совпадений с HTML-тэгами


<?php
// Запись \\2 является примером использования ссылок на подмаски.
// Она означает необходимость соответствия подстроки строке, захваченной
// второй подмаской, в нашем примере это ([\w]+).
// Дополнительный обратный слэш необходим, так как используются двойные кавычки.
$html = "<b>полужирный текст</b><a href=howdy.html>нажми</a>";

preg_match_all("/(<([\w]+)[^>]*>)(.*?)(<\/\\2>)/", $html, $matches, PREG_SET_ORDER);

foreach ($matches as $val) {
    echo "совпадение: " . $val[0] . "\n";
    echo "часть 1: " . $val[1] . "\n";
    echo "часть 2: " . $val[2] . "\n";
    echo "часть 3: " . $val[3] . "\n";
    echo "часть 4: " . $val[4] . "\n\n";
}
?>

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

совпадение: <b>полужирный текст</b>
часть 1: <b>
часть 2: b
часть 3: полужирный текст
часть 4: </b>

matched: <a href=hody.html>нажми</a>
часть 1: <a href=howdy.html>
часть 2: a
часть 3: нажми
часть 4: </a>

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


<?php

$str = <<<FOO
a: 1
b: 2
c: 3
FOO;

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

/* Это также работает в PHP 5.2.2 (PCRE 7.0) и более поздних версиях,
 * однако, вышеуказанная форма рекомендуется для обратной совместимости */
// preg_match_all('/(?<name>\w+): (?<digit>\d+)/', $str, $matches);

print_r($matches);

?>

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

Array
(
    [0] => Array
        (
            [0] => a: 1
            [1] => b: 2
            [2] => c: 3
        )

    [name] => Array
        (
            [0] => a
            [1] => b
            [2] => c
        )

    [1] => Array
        (
            [0] => a
            [1] => b
            [2] => c
        )

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

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

)

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

"Регулярные выражения PCRE"
preg_match() - Выполняет проверку на соответствие регулярному выражению
preg_replace() - Выполняет поиск и замену по регулярному выражению
preg_split() - Разбивает строку по регулярному выражению
preg_last_error() - Возвращает код ошибки выполнения последнего регулярного выражения PCRE