preg_grep()

Возвращает массив вхождений, которые соответствуют шаблону
(PHP 4, PHP 5)

Описание

array preg_grep ( string pattern, array input [, int flags] )

preg_grep() возвращает массив, состоящий из элементов входящего массива input, которые соответствуют заданному шаблону pattern.

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

PREG_GREP_INVERT

В случае, если этот флаг установлен, функция preg_grep(), возвращает те элементы массива, которые не соответствуют заданному шаблону pattern. Этот флаг доступен, начиная с PHP 4.2.0.

Начиная с PHP 4.0.4, результат, возвращаемый функцией preg_grep() использует те же индексы, что и массив исходных данных. Если такое поведение вам не подходит, примените array_values() к массиву, возвращаемому preg_grep() для реиндексации.

Пример

<?php
// Возвращает все элементы массива,
// содержащие числа с плавающей точкой$fl_array = preg_grep("/^(\d+)?\.\d+$/", $array);
?>

preg_last_error()

Возвращает код ошибки выполнения последнего PCRE

Описание

int preg_last_error ( void )

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

Возвращает одну из следующих констант:

PREG_NO_ERROR
PREG_INTERNAL_ERROR
PREG_BACKTRACK_LIMIT_ERROR (see also pcre.backtrack_limit)
PREG_RECURSION_LIMIT_ERROR (see also pcre.recursion_limit)
PREG_BAD_UTF8_ERROR

preg_match_all()

Выполняет глобальный поиск шаблона в строке (PHP 3 >= 3.0.9, PHP 4, PHP 5)

Описание

int preg_match_all ( string pattern, string subject, array &matches [, int flags [, int offset]] )

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

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

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

PREG_PATTERN_ORDER

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

<?php 
preg_match_all("|<[^>]+>(.*)]+>|U","example:<div align=left>this is a test</div>",
$out, PREG_PATTERN_ORDER);
echo $out[0][0] . ", " . $out[0][1] . "\n";
echo $out[1][0] . ", " . $out[1][1] . "\n";
?>

Результат работы примера:

<b>example:</b>, <div align=left>this is a test</div>
example:, this is a test

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

PREG_SET_ORDER

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

<?php
preg_match_all("|<[^>]+>(.*)]+>|U","<b>example:<div align=\"left\">this is a test</div>",
$out,PREG_SET_ORDER);
echo $out[0][0] . ", " . $out[0][1] . "\n";
echo $out[1][0] . ", " . $out[1][1] . "\n";
?>

Результат работы примера:

<b>example:</b>, example:<div align="left">this is a test</div>, this is a test

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

PREG_OFFSET_CAPTURE

В случае, если этот флаг указан, для каждой найденной подстроки будет указана ее позиция в исходной строке. Необходимо помнить, что этот флаг меняет формат возвращаемых данных: каждое вхождение возвращается в виде массива, в нулевом элементе которого содержится найденная подстрока, а в первом - смещение. Данный флаг доступен в PHP 4.3.0 и выше.

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

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

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

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

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

<?phppreg_match_all("/\(?(\d{3})?\)?(?(1)[\-\s])\d{3}-\d{4}/x","Call 555-1212 or 1-800-555-1212", $phones);
?>

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

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

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

for ($i=0; $i< count($matches[0]); $i++) {
echo "matched: " . $matches[0][$i] . "\n";
echo "part 1: " . $matches[1][$i] . "\n";
echo "part 2: " . $matches[3][$i] . "\n";
echo "part 3: " . $matches[4][$i] . "\n\n";
}
?>

Результат работы примера:

matched: <b>bold text</b>
part 1: <b>
part 2: bold textpart 3: </b>
matched: <a href=howdy.html>click me</a>
part 1: <a href=howdy.html>
part 2: click mepart 3: </a>

preg_match()

Выполняет проверку на соответствие регулярному выражению (PHP 3 >= 3.0.9, PHP 4, PHP 5)

Описание:

mixed preg_match ( string pattern, string subject [, array &matches [, int flags [, int offset]]] )

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

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

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

PREG_OFFSET_CAPTURE

В случае, если этот флаг указан, для каждой найденной подстроки будет указана ее позиция в исходной строке. Необходимо помнить, что этот флаг меняет формат возвращаемых данных: каждое вхождение возвращается в виде массива, в нулевом элементе которого содержится найденная подстрока, а в первом - смещение. Данный флаг доступен в PHP 4.3.0 и выше.

Дополнительный параметр flags доступен начиная с PHP 4.3.0.

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

Замечание: Использование параметра offset не эквивалентно замене сопоставляемой строки выражением substr($subject, $offset) при вызове функции preg_match_all(), поскольку шаблон 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() возвращает количество найденных соответствий. Это может быть 0 (совпадения не найдены) и 1, поскольку preg_match() прекращает свою работу после первого найденного совпадения. Если необходимо найти либо сосчитать все совпадения, следует воспользоваться функцией preg_match_all(). Функция preg_match() возвращает FALSE в случае, если во время выполнения возникли какие-либо ошибки.

Подсказка: Не используйте функцию preg_match(), если необходимо проверить наличие подстроки в заданной строке. Используйте для этого strpos() либо strstr(), поскольку они выполнят эту задачу гораздо быстрее.

Пример. Поиск подстроки "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 "Вхождение не найдено.";
}
?>

Пример. Извлечение доменного имени из URL

<?php
// Извлекаем имя хоста из URL
preg_match("/^(http:\/\/)?([^\/]+)/i",
"http://www.php.net/index.html", $matches);
$host = $matches[2];

// извлекаем две последние части имени хостаpreg_match("/[^\.\/]+\.[^\.\/]+$/", $host, $matches);
echo "domain name is: {$matches[0]}\n";
?>

Результат работы примера:

domain name is: php.net

preg_quote()

Экранирует символы в регулярных выражениях
(PHP 3 >= 3.0.9, PHP 4, PHP 5)

Описание

string preg_quote ( string str [, string delimiter] )

Функция preg_quote() принимает строку str и добавляет обратный слеш перед каждым служебным символом. Это бывает полезно, если в составлении шаблона участвуют строковые переменные, значение которых в процессе работы скрипта может меняться.

В случае, если дополнительный параметр delimiter указан, он будет также экранироваться. Это удобно для экранирования ограничителя, который используется в PCRE функциях. Наиболее распространенным ограничителем является символ '/'.

В регулярных выражениях служебными считаются следующие символы: . \\ + * ? [ ^ ] $ ( ) { } = ! < > | :

preg_quote() пример

<?php$keywords = "$40 for a g3/400";
$keywords = preg_quote($keywords, "/");
echo $keywords; // возвращает \$40 for a g3\/400
?>

Пример. Выделение курсивом слова в тексте

<?php
// В данном примере preg_quote($word) используется, чтобы
// избежать трактовки символа '*' как спец. символа.
$textbody = "This book is *very* difficult to find.";
$word = "*very*";
$textbody = preg_replace ("/" . preg_quote($word) . "/",
"" . $word . "",
$textbody);
?>

preg_replace_callback()

Выполняет поиск по регулярному выражению и замену с использованием функции обратного вызова
(PHP 4 >= 4.0.5, PHP 5)

Описание

mixed preg_replace_callback ( mixed pattern, callback callback, mixed subject [, int limit] )

Поведение этой функции во многом напоминает preg_replace(), за исключением того, что вместо параметра replacement необходимо указывать callback функцию, которой в качестве входящего параметра передается массив найденных вхождений. Ожидаемый результат - строка, которой будет произведена замена.

preg_replace_callback() пример

<?php
// Этот текст был использован в 2002 году
// мы хотим обновить даты к 2003 году
$text = "April fools day is 04/01/2002\n";
$text.= "Last christmas was 12/24/2001\n";

// функция обратного вызова
function next_year($matches)
{
// как обычно: $matches[0] - полное вхождение шаблона
// $matches[1] - вхождение первой подмаски,
// заключенной в круглые скобки, и так далее...
return $matches[1].($matches[2]+1);
}

echo preg_replace_callback(
"|(\d{2}/\d{2}/)(\d{4})|",
"next_year",
$text);

// результат:
// April fools day is 04/01/2003
// Last christmas was 12/24/2002
?>

Достаточно часто callback функция, кроме как в вызове preg_replace_callback(), ни в чем больше не участвует. Исходя из этих соображений, можно использовать create_function() для создания безымянной функции обратного вызова непосредственно в вызове preg_replace_callback(). Если вы используете такой подход, вся информация, связанная с заменой по регулярному выражению, будет собрана в одном месте, и пространство имен функций не будет загромождаться неиспользуемыми записями.

Пример. preg_replace_callback() и create_function()

<?php
/* фильтр, подобный тому, что используется в системах Unix
* для преобразования в заглавные начальных букв параграфа */

$fp = fopen("php://stdin", "r") or die("can't read stdin");
while (!feof($fp)) {
$line = fgets($fp);
$line = preg_replace_callback(
'|

\s*\w|',
create_function(
// Использование одиночных кавычек в данном случае принципиально,
// альтернатива - экранировать все символы '$'
'$matches',
'return strtolower($matches[0]);'
),
$line
);
echo $line;
}
fclose($fp);
?>

preg_replace()

Выполняет поиск и замену по регулярному выражению
(PHP 3 >= 3.0.9, PHP 4, PHP 5)

Описание

mixed preg_replace ( mixed pattern, mixed replacement, mixed subject [, int limit] )

Выполняет поиск в строке subject совпадений с шаблоном pattern и заменяет их на replacement. В случае, если параметр limit указан, будет произведена замена limit вхождений шаблона; в случае, если limit опущен либо равняется -1, будут заменены все вхождения шаблона.

Replacement может содержать ссылки вида \\n либо (начиная с PHP 4.0.4) $n, причем последний вариант предпочтительней. Каждая такая ссылка, будет заменена на подстроку, соответствующую n'нной заключенной в круглые скобки подмаске. n может принимать значения от 0 до 99, причем ссылка \\0 (либо $0) соответствует вхождению всего шаблона. Подмаски нумеруются слева направо, начиная с единицы.

При использовании замены по шаблону с использованием ссылок на подмаски может возникнуть ситуация, когда непосредственно за маской следует цифра. В таком случае нотация вида \\n приводит к ошибке: ссылка на первую подмаску, за которой следует цифра 1, запишется как \\11, что будет интерпретировано как ссылка на одиннадцатую подмаску. Это недоразумение можно устранить, если воспользоваться конструкцией \${1}1, указывающей на изолированную ссылку на первую подмаску, и следующую за ней цифру 1.

Пример 1. Использование подмасок, за которыми следует цифра

<?php$string = "April 15, 2003";
$pattern = "/(\w+) (\d+), (\d+)/i";
$replacement = "\${1}1,\$3";
echo preg_replace($pattern, $replacement, $string);
?>

Результатом работы этого примера будет:

April1,2003

Если во время выполнения функции были обнаружены совпадения с шаблоном, будет возвращено измененное значение subject, в противном случае будет возвращен исходный текст subject.

Первые три параметра функции preg_replace() могут быть одномерными массивами. В случае, если массив использует ключи, при обработке массива они будут взяты в том порядке, в котором они расположены в массиве. Указание ключей в массиве для pattern и replacement не является обязательным. Если вы все же решили использовать индексы, для сопоставления шаблонов и строк, участвующих в замене, используйте функцию ksort() для каждого из массивов.

Пример. Использование массивов с числовыми индексами в качестве аргументов функции preg_replace()

<?php$string = "The quick brown fox jumped over the lazy dog.";

$patterns[0] = "/quick/";
$patterns[1] = "/brown/";
$patterns[2] = "/fox/";

$replacements[2] = "bear";
$replacements[1] = "black";
$replacements[0] = "slow";

echo preg_replace($patterns, $replacements, $string);
?>

Результат:

The bear black slow jumped over the lazy dog.

Используя ksort(), получаем желаемый результат:

<?php
ksort($patterns);
ksort($replacements);

echo preg_replace($patterns, $replacements, $string);

?>

Результат:

The slow black bear jumped over the lazy dog.

В случае, если параметр subject является массивом, поиск и замена по шаблону производятся для каждого из его элементов. Возвращаемый результат также будет массивом.

В случае, если параметры pattern и replacement являются массивами, preg_replace() поочередно извлекает из обоих массивов по паре элементов и использует их для операции поиска и замены. Если массив replacement содержит больше элементов, чем pattern, вместо недостающих элементов для замены будут взяты пустые строки. В случае, если pattern является массивом, а replacement - строкой, по каждому элементу массива pattern будет осущесвтлен поиск и замена на pattern (шаблоном будут поочередно все элементы массива, в то время как строка замены остается фиксированной). Вариант, когда pattern является строкой, а replacement - массивом, не имеет смысла.

Модификатор /e меняет поведение функции preg_replace() таким образом, что параметр replacement после выполнения необходимых подстановок интерпретируется как PHP-код и только после этого используется для замены. Используя данный модификатор, будьте внимательны: параметр replacement должен содержать корректный PHP-код, в противном случае в строке, содержащей вызов функции preg_replace(), возникнет ошибка синтаксиса.

Пример. Замена по нескольким шаблонам

<?php$patterns = array ("/(19|20)(\d{2})-(\d{1,2})-(\d{1,2})/",
"/^\s*{(\w+)}\s*=/");
$replace = array ("\\3/\\4/\\1\\2", "$\\1 =");
echo preg_replace($patterns, $replace, "{startDate} = 1999-5-27");
?>

Этот пример выведет:

$startDate = 5/27/1999

Пример. Использование модификатора /e

<?phppreg_replace("/(<\/?)(\w+)([^>]*>)/e",
"'\\1'.strtoupper('\\2').'\\3'",
$html_body);
?>

Преобразует все HTML-теги к верхнему регистру

Пример. Конвертор HTML в текст

<?php
// $document на выходе должен содержать HTML-документ.
// Необходимо удалить все HTML-теги, секции javascript,
// пробельные символы. Также необходимо заменить некоторые
// HTML-сущности на их эквивалент.
$search = array ("']*?>.*?'si", // Вырезает javaScript
"'<[\/\!]*?[^<>]*?>'si", // Вырезает HTML-теги
"'([\r\n])[\s]+'", // Вырезает пробельные символы
"'&(quot|#34);'i", // Заменяет HTML-сущности
"'&(amp|#38);'i",
"'&(lt|#60);'i",
"'&(gt|#62);'i",
"'&(nbsp|#160);'i",
"'&(iexcl|#161);'i",
"'&(cent|#162);'i",
"'&(pound|#163);'i",
"'&(copy|#169);'i",
"'&#(\d+);'e"); // интерпретировать как php-код
$replace = array ("",
"",
"\\1",
"\"",
"&",
"<",
">",
" ",
chr(161),
chr(162),
chr(163),
chr(169),
"chr(\\1)");

$text = preg_replace($search, $replace, $document);
?>

Замечание: Параметр limit доступен в PHP 4.0.1pl2 и выше.

preg_split()

Разбивает строку по регулярному выражению (PHP 3 >= 3.0.9, PHP 4, PHP 5)

Описание

array preg_split ( string pattern, string subject [, int limit [, int flags]] )

Возвращает массив, состоящий из подстрок заданной строки subject, которая разбита по границам, соответствующим шаблону pattern.

В случае, если параметр limit указан, функция возвращает не более, чем limit подстрок. Специальное значение limit, равное -1, подразумевает отсутствие ограничения, это весьма полезно для указания еще одного опционального параметра flags.

flags может быть произвольной комбинацией следующих флагов (соединение происходит при помощи оператора '|'):

PREG_SPLIT_NO_EMPTY

В случае, если этот флаг указан, функция preg_split() вернет только непустые подстроки.
PREG_SPLIT_DELIM_CAPTURE

В случае, если этот флаг указан, выражение, заключенное в круглые скобки в разделяющем шаблоне, также извлекается из заданной строки и возвращается функцией. Этот флаг был добавлен в PHP 4.0.5.
PREG_SPLIT_OFFSET_CAPTURE

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

Пример 1. preg_split() пример: Получение подстрок из заданного текста

<?php
// разбиваем строку по произвольному числу запятых и пробельных символов,
// которые включают в себя " ", \r, \t, \n и \f$keywords = preg_split("/[\s,]+/", "hypertext language, programming");
?>

Пример 2. Разбиваем строку на составляющие символы

<?php$str = 'string';
$chars = preg_split('//', $str, -1, PREG_SPLIT_NO_EMPTY);
print_r($chars);
?>

Пример 3. Разбиваем строку с указанием смещения для каждой из найденных подстрок

<?php$str = 'hypertext language programming';
$chars = preg_split('/ /', $str, -1, PREG_SPLIT_OFFSET_CAPTURE);
print_r($chars);
?>

На выходе получаем:

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

[1] => Array
(
[0] => language
[1] => 10
)

[2] => Array
(
[0] => programming
[1] => 19
)

)

Замечание: Параметр flags был добавлен в PHP 4 Beta 3.