preg_match_all
string$pattern,
string$subject,
[array
[int$flags = 0],
[int$offset = 0]
): int|false
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
- pattern
-
The pattern to search for, as a string.
- subject
-
The input string.
- matches
-
Array of all matches in multi-dimensional array ordered according to flags.
- 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):
- 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] . "\n";
echo $out[1][0] . ", " . $out[1][1] . "\n";
?>The above example will output:
example: ,this is a testexample: , 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.
If the pattern contains named subpatterns, $matches additionally contains entries for keys with the subpattern name.
If the pattern contains duplicate named subpatterns, only the rightmost subpattern is stored in $matches[NAME].
<?php
preg_match_all(
'/(?J)(?<match>foo)|(?<match>bar)/',
'foo bar',
$matches,
PREG_PATTERN_ORDER
);
print_r($matches['match']);
?>The above example will output:
Array
(
[0] =>
[1] => bar
) - 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] . "\n";
echo $out[1][0] . ", " . $out[1][1] . "\n";
?>The above example will output:
example: , example:this is a test, this is a test ]]> - PREG_OFFSET_CAPTURE
-
If this flag is passed, for every occurring match the appendant string offset (in bytes) will also be returned. Note that this changes the value of matches into an array of arrays where every element is an array consisting of the matched string at offset 0 and its string offset into subject at offset 1.
<?php
preg_match_all('/(foo)(bar)(baz)/', 'foobarbaz', $matches, PREG_OFFSET_CAPTURE);
print_r($matches);
?>The above example will output:
Array
(
[0] => Array
(
[0] => Array
(
[0] => foobarbaz
[1] => 0
)
)
[1] => Array
(
[0] => Array
(
[0] => foo
[1] => 0
)
)
[2] => Array
(
[0] => Array
(
[0] => bar
[1] => 3
)
)
[3] => Array
(
[0] => Array
(
[0] => baz
[1] => 6
)
)
) - PREG_UNMATCHED_AS_NULL
-
If this flag is passed, unmatched subpatterns are reported as null; otherwise they are reported as an empty string.
If no order flag is given, PREG_PATTERN_ORDER is assumed.
- 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 in place of the subject string, because pattern can contain assertions such as ^, $ or (?<=x). See preg_match for examples.
Return Values
Returns the number of full pattern matches (which might be zero), or false on failure.
Exceptions and Errors
If the regex pattern passed does not compile to a valid regex, an E_WARNING is emitted.
Changelog
| Version | Description |
| 7.2.0 | The PREG_UNMATCHED_AS_NULL is now supported for the $flags parameter. |