PCRE
PHP Manual

preg_match

(PHP 4, PHP 5)

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

Описание

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

Ищет в заданном тексте subject совпадения с шаблоном pattern.

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

pattern

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

subject

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

matches

В случае, если указан дополнительный параметр matches, он будет заполнен результатами поиска. Элемент $matches[0] будет содержать часть строки, соответствующую вхождению всего шаблона, $matches[1] - часть строки, соответствующую первой подмаске, и так далее.

flags

flags может принимать значение следующего флага:

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

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
        )

)

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

Функция preg_match() возвращает количество найденных соответствий шаблона pattern. Это может быть 0 (совпадения не найдены) и 1, поскольку preg_match() прекращает свою работу после первого найденного совпадения. Функция же preg_match_all(), наоборот, будет продолжать свою работу пока не достигнет конца subject. Функция preg_match() возвращает FALSE в случае, если во время выполнения возникли какие-либо ошибки.

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

Версия Описание
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
4.3.0 Добавлен параметр 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 "Вхождение не найдено.";
}

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

/* Это также работает в PHP 5.2.2 (PCRE 7.0) и более поздних версиях,
 * однако, вышеуказанная форма рекомендуется для обратной совместимости */
// 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() либо strstr(), поскольку они выполнят эту задачу гораздо быстрее.

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

PCRE
PHP Manual