PHP preg_match_all
Summary: in this tutorial, you’ll learn how to use the PHP preg_match_all() function to search for all matches to a regular expression in a string.
Introduction to the PHP preg_match_all() function
The preg_match_all() function searches for all the matches to a regular expression in a string.
Unlike the preg_match() function that stops searching when it finds the first match, the preg_match_all() function continues searching for the next matches till the end of the string.
The following shows the syntax of the preg_match_all() function:
preg_match_all(
string $pattern,
string $subject,
array &$matches = null,
int $flags = 0,
int $offset = 0
): int|false|nullCode language: PHP (php)
The preg_match_all() function accepts the following parameters:
$patternis a string that specifies the pattern to search.$subjectis the input string to match the pattern.$matchesis a multi-dimensional array that contains all the matches.$flagsis a combination of the flagsPREG_PATTERN_ORDER,PREG_SET_ORDER,PREG_OFFSET_CAPTURE, andPREG_UNMATCHED_AS_NULL. By default, the$flagsisPREG_PATTERN_ORDERif you skip it.$offsetis an integer that specifies the position from which the search starts. By default, thepreg_match_all()function starts searching from the beginning of the string.
The preg_match_all() function returns a number that specifies the number of full pattern matches. If there is no match, the preg_match_all() function returns zero. In case of failure, it returns false.
PHP preg_match_all() function examples
Let’s take some examples of using the preg_match_all() function.
1) Using the PHP preg_match_all() function to match numbers in a string example
The following example uses the preg_match_all() function to search for all numbers with one or more digits in a string:
$pattern = '/\d+/';
$str = 'PHP 1.0 released in 1995';
if (preg_match_all($pattern, $str, $matches)) {
print_r($matches);
}
Code language: PHP (php)
Output:
Array
(
[0] => Array
(
[0] => 1
[1] => 0
[2] => 1995
)
)Code language: PHP (php)
It returns three matches 0, 1, and 1995. If you use the preg_match() function, it’ll return the first number (1) only.
2) Using the preg_match_all() function with flags parameters
The following example uses the preg_match_all() function to match the word in a string. It also captures the first character of each word:
$pattern = '/\b([a-zA-Z])\w+\b/';
$str = 'Alice, Bob, Peter';
if (preg_match_all($pattern, $str, $matches)) {
print_r($matches);
}
Code language: PHP (php)
Output:
Array
(
[0] => Array
(
[0] => Alice
[1] => Bob
[2] => Peter
) [1] => Array
(
[0] => A
[1] => B
[2] => P
)
)
Code language: PHP (php)
The $matches array contains the full pattern matches in the first element and the capturing groups in the second element. It returns the same result as if you use the PREG_PATTERN_ORDER flag.
If you want to group each set of matches in an array element, you can use the PREG_SET_ORDER flag.
The PREG_SET_ORDER flag groups the first set of matches in the $matches[0], the second est of matches in the $matches[1], and so on. For example:
$pattern = '/\b([a-zA-Z])\w+\b/';
$str = 'Alice, Bob, Peter';
if (preg_match_all($pattern, $str, $matches, PREG_SET_ORDER)) {
print_r($matches);
}
Code language: PHP (php)
Output:
Array
(
[0] => Array
(
[0] => Alice
[1] => A
) [1] => Array
(
[0] => Bob
[1] => B
)
[2] => Array
(
[0] => Peter
[1] => P
)
)
Code language: PHP (php)
The $flags can also be:
PREG_OFFSET_CAPTUREreturns the offset of the match together with the matched string.PREG_UNMATCHED_AS_NULLreturnsNULLinstead of an empty string if no match is found for the subpatterns a.k.a capturing groups.
To combine flags, you place the | operator between two of them. For example:
$pattern = '/\b([a-zA-Z])\w+\b/';
$str = 'Alice, Bob, Peter';
if (preg_match_all($pattern, $str, $matches, PREG_SET_ORDER | PREG_OFFSET_CAPTURE)) {
print_r($matches);
}
Code language: PHP (php)
Output:
Array
(
[0] => Array
(
[0] => Array
(
[0] => Alice
[1] => 0
) [1] => Array
(
[0] => A
[1] => 0
)
)
[1] => Array
(
[0] => Array
(
[0] => Bob
[1] => 7
)
[1] => Array
(
[0] => B
[1] => 7
)
)
[2] => Array
(
[0] => Array
(
[0] => Peter
[1] => 12
)
[1] => Array
(
[0] => P
[1] => 12
)
)
)
Code language: PHP (php)
Note that it doesn’t make sense to combine PREG_PATTERN_ORDER and PREG_SET_ORDER flags.
Summary
- Use the PHP
preg_match_all()function to search for all matches in a string.