PREG_MATCH_ALL(3) 1 PREG_MATCH_ALL(3)
preg_match_all - Perform a global regular expression match
SYNOPSIS
int preg_match_all PREG_PATTERN_ORDER (string $pattern, string $subject, [array &$matches], [int $flags], [int $offset])
DESCRIPTION
Searches $subject for all matches to the regular expression given in $pattern and puts them in $matches in the order specified by $flags.
After the first match is found, the subsequent searches are continued on from end of the last match.
PARAMETERS
o $pattern
- The pattern to search for, as a string.
o $subject
- The input string.
o $matches
- Array of all matches in multi-dimensional array ordered according to $flags.
o $flags
- Can be a combination of the following flags (note that it doesn't make sense to use PREG_PATTERN_ORDER together with
PREG_SET_ORDER):
o PREG_PATTERN_ORDER - Orders results so that $matches[0] is an array of full pattern matches, $matches[1] is an array of
strings matched by the first parenthesized subpattern, and so on.
<?php
preg_match_all("|<[^>]+>(.*)</[^>]+>|U",
"<b>example: </b><div align=left>this is a test</div>",
$out, PREG_PATTERN_ORDER);
echo $out[0][0] . ", " . $out[0][1] . "
";
echo $out[1][0] . ", " . $out[1][1] . "
";
?>
The above example will output:
<b>example: </b>, <div align=left>this is a test</div>
example: , this is a test
So, $out[0] contains array of strings that matched full pattern, and $out[1] contains array of strings enclosed by tags.
o PREG_SET_ORDER - Orders results so that $matches[0] is an array of first set of matches, $matches[1] is an array of second
set of matches, and so on.
<?php
preg_match_all("|<[^>]+>(.*)</[^>]+>|U",
"<b>example: </b><div align="left">this is a test</div>",
$out, PREG_SET_ORDER);
echo $out[0][0] . ", " . $out[0][1] . "
";
echo $out[1][0] . ", " . $out[1][1] . "
";
?>
The above example will output:
<b>example: </b>, example:
<div align="left">this is a test</div>, this is a test
o PREG_OFFSET_CAPTURE - If this flag is passed, for every occurring match the appendant string offset will also be returned.
Note that this changes the value of $matches into an array where every element is an array consisting of the matched string
at offset 0 and its string offset into $subject at offset 1.
If no order flag is given, PREG_PATTERN_ORDER is assumed.
o $offset
- Normally, the search starts from the beginning of the subject string. The optional parameter $offset can be used to specify the
alternate place from which to start the search (in bytes).
Note
Using $offset is not equivalent to passing substr($subject, $offset) to preg_match_all(3) in place of the subject string,
because $pattern can contain assertions such as ^, $ or (?<=x). See preg_match(3) for examples.
RETURN VALUES
Returns the number of full pattern matches (which might be zero), or FALSE if an error occurred.
CHANGELOG
+--------+---------------------------------------------------+
|Version | |
| | |
| | Description |
| | |
+--------+---------------------------------------------------+
| 5.4.0 | |
| | |
| | The $matches parameter became optional. |
| | |
| 5.3.6 | |
| | |
| | Returns FALSE if $offset is higher than $subject |
| | length. |
| | |
| 5.2.2 | |
| | |
| | Named subpatterns now accept the syntax |
| | (?<name>) and (?'name') as well as (?P<name>). |
| | Previous versions accepted only (?P<name>). |
| | |
+--------+---------------------------------------------------+
EXAMPLES
Example #1
Getting all phone numbers out of some text.
<?php
preg_match_all("/(? (d{3})? )? (?(1) [-s] ) d{3}-d{4}/x",
"Call 555-1212 or 1-800-555-1212", $phones);
?>
Example #2
Find matching HTML tags (greedy)
<?php
// The \2 is an example of backreferencing. This tells pcre that
// it must match the second set of parentheses in the regular expression
// itself, which would be the ([w]+) in this case. The extra backslash is
// required because the string is in double quotes.
$html = "<b>bold text</b><a href=howdy.html>click me</a>";
preg_match_all("/(<([w]+)[^>]*>)(.*?)(</\2>)/", $html, $matches, PREG_SET_ORDER);
foreach ($matches as $val) {
echo "matched: " . $val[0] . "
";
echo "part 1: " . $val[1] . "
";
echo "part 2: " . $val[2] . "
";
echo "part 3: " . $val[3] . "
";
echo "part 4: " . $val[4] . "
";
}
?>
The above example will output:
matched: <b>bold text</b>
part 1: <b>
part 2: b
part 3: bold text
part 4: </b>
matched: <a href=howdy.html>click me</a>
part 1: <a href=howdy.html>
part 2: a
part 3: click me
part 4: </a>
Example #3
Using named subpattern
<?php
$str = <<<FOO
a: 1
b: 2
c: 3
FOO;
preg_match_all('/(?P<name>w+): (?P<digit>d+)/', $str, $matches);
/* This also works in PHP 5.2.2 (PCRE 7.0) and later, however
* the above form is recommended for backwards compatibility */
// preg_match_all('/(?<name>w+): (?<digit>d+)/', $str, $matches);
print_r($matches);
?>
The above example will output:
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
)
)
SEE ALSO
PCRE Patterns, preg_quote(3), preg_match(3), preg_replace(3), preg_split(3), preg_last_error(3).
PHP Documentation Group PREG_MATCH_ALL(3)