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:

• $pattern is a string that specifies the pattern to search.
• $subject is the input string to match the pattern.
• $matches is a multi-dimensional array that contains all the matches.
• $flags is a combination of the flags PREG_PATTERN_ORDER, PREG_SET_ORDER, PREG_OFFSET_CAPTURE, and PREG_UNMATCHED_AS_NULL. By default, the $flags is PREG_PATTERN_ORDER if you skip it.
• $offset is an integer that specifies the position from which the search starts. By default, the preg_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:

<?php

$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:

<?php

$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:

<?php

$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_CAPTURE returns the offset of the match together with the matched string.
• PREG_UNMATCHED_AS_NULL returns NULL instead 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:

<?php

$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.