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


(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$matchesPREG_OFFSET_CAPTURE3);
print_r($matches);
?>

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

 Array ( ) 

В то время как этот пример

<?php
$subject 
"abcdef";
$pattern '/^def/';
preg_match($patternsubstr($subject,3), $matchesPREG_OFFSET_CAPTURE);
print_r($matches);
?>

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

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

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

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

Внимание

Эта функция может возвращать как boolean FALSE, так и не-boolean значение, которое приводится к FALSE. За более подробной информацией обратитесь к разделу Булев тип. Используйте оператор === для проверки значения, возвращаемого этой функцией.

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

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

Примеры

Пример #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"
  • preg_quote() - Экранирует символы в регулярных выражениях
  • preg_match_all() - Выполняет глобальный поиск шаблона в строке
  • preg_replace() - Выполняет поиск и замену по регулярному выражению
  • preg_split() - Разбивает строку по регулярному выражению
  • preg_last_error() - Возвращает код ошибки выполнения последнего регулярного выражения PCRE