preg_match_all

Description
Syntax
Examples
Links

Description

The preg_match_all of PCRE for PHP perform a global regular expression match.

Syntax

preg_match_all(
    string $pattern,
    string $subject,
    array &$matches = null,
    int $flags = 0,
    int $offset = 0
): int|false

Parameters

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

Contant	Description
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. 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].
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.
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 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.
PREG_UNMATCHED_AS_NULL	If this flag is passed, unmatched subpatterns are reported as NULL; otherwise they are reported as an empty string.

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

Returns the number of full pattern matches (which might be zero), or false on failure.

Examples

1 · pattern subject · case-sensitive

<?

$pattern = "#php#";
$subject = "PHP stands for PHP: Hypertext Preprocessor";

$return = preg_match_all($pattern, $subject);

echo $return;

2 · pattern subject · case-insensitive

<?

$pattern = "#php#i";
$subject = "PHP stands for PHP: Hypertext Preprocessor";

$return = preg_match_all($pattern, $subject);

echo $return;

3 · matches

<?

$pattern = "#php#i";
$subject = "PHP stands for PHP: Hypertext Preprocessor";

preg_match_all($pattern, $subject, $matches);

print_r($matches);

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

)

4 · flags · PREG_PATTERN_ORDER

<?

$pattern = "#<[^>]+>(.*)</[^>]+>#U";
$subject = "<p>paragraph</p><span>span</span>";
$flags = PREG_PATTERN_ORDER;

preg_match_all($pattern, $subject, $matches, $flags);

print_r($matches);

Array
(
    [0] => Array
        (
            [0] => <p>paragraph</p>
            [1] => <span>span</span>
        )

    [1] => Array
        (
            [0] => paragraph
            [1] => span
        )

)

5 · flags · PREG_PATTERN_ORDER · Named Subpattern

<?

$pattern = "#(?J)(?<match>named)|(?<match>subpattern)#";
$subject = "named subpattern";
$flags = PREG_PATTERN_ORDER;

preg_match_all($pattern, $subject, $matches, $flags);

print_r($matches);

Array
(
    [0] => Array
        (
            [0] => named
            [1] => subpattern
        )

    [match] => Array
        (
            [0] => 
            [1] => subpattern
        )

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

    [2] => Array
        (
            [0] => 
            [1] => subpattern
        )

)

6 · flags · PREG_SET_ORDER

<?

$pattern = "#<[^>]+>(.*)</[^>]+>#U";
$subject = "<p>paragraph</p><span>span</span>";
$flags = PREG_SET_ORDER;

preg_match_all($pattern, $subject, $matches, $flags);

print_r($matches);

Array
(
    [0] => Array
        (
            [0] => <p>paragraph</p>
            [1] => paragraph
        )

    [1] => Array
        (
            [0] => <span>span</span>
            [1] => span
        )

)

7 · flags · PREG_OFFSET_CAPTURE

<?

$pattern = "#(preg)(offset)(capture)#";
$subject = "pregoffsetcapture";
$flags = PREG_OFFSET_CAPTURE;

preg_match_all($pattern, $subject, $matches, $flags);

print_r($matches);

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

        )

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

        )

    [2] => Array
        (
            [0] => Array
                (
                    [0] => offset
                    [1] => 4
                )

        )

    [3] => Array
        (
            [0] => Array
                (
                    [0] => capture
                    [1] => 10
                )

        )

)

8 · flags · PREG_UNMATCHED_AS_NULL

<?

$pattern = "#(preg)(unmatched)*(as)#";
$subject = "pregas";
$flags = PREG_UNMATCHED_AS_NULL;

preg_match_all($pattern, $subject, $matches1);
preg_match_all($pattern, $subject, $matches2, $flags);

var_export($matches1);
echo PHP_EOL;
var_export($matches2);

array (
  0 => 
  array (
    0 => 'pregas',
  ),
  1 => 
  array (
    0 => 'preg',
  ),
  2 => 
  array (
    0 => '',
  ),
  3 => 
  array (
    0 => 'as',
  ),
)
array (
  0 => 
  array (
    0 => 'pregas',
  ),
  1 => 
  array (
    0 => 'preg',
  ),
  2 => 
  array (
    0 => NULL,
  ),
  3 => 
  array (
    0 => 'as',
  ),
)

9 · offset

<?

$pattern = "#offset#";
$subject = "offset offset offset";
$flags = PREG_OFFSET_CAPTURE;
$offset = 1;

preg_match_all($pattern, $subject, $matches, $flags, $offset);

print_r($matches);

Array
(
    [0] => Array
        (
            [0] => Array
                (
                    [0] => offset
                    [1] => 7
                )

            [1] => Array
                (
                    [0] => offset
                    [1] => 14
                )

        )

)

10 · phone

<?

$pattern = "#\(? (\d{3})? \)? (?(1) [\-\s]) \d{3}-\d{4}#x";
$subject = "Call 555-1212 or 1-800-555-1212";

preg_match_all($pattern, $subject, $matches);

print_r($matches);

Array
(
    [0] => Array
        (
            [0] => 555-1212
            [1] => 800-555-1212
        )

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

)

11 · named subpattern

<?

$pattern = "#(?<name>\w+): (?<digit>\d+)#";
$subject = "a: 1 b: 2 c: 3";

preg_match_all($pattern, $subject, $matches);

print_r($matches);

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
        )

)

12 · HTML

<?

// \\2 is an example of backreferencing. it matches the second set of parentheses in the regular expression which is ([\w]+) in this case. an extra backslash is required because the string is in double quotes.

$pattern = "#(<([\w]+)[^>]*>)(.*?)(<\/\\2>)#";
$subject = '<b>bold</b><a href="#">anchor</a>';
$flags = PREG_SET_ORDER;

preg_match_all($pattern, $subject, $matches, $flags);

print_r($matches);

Array
(
    [0] => Array
        (
            [0] => <b>bold</b>
            [1] => <b>
            [2] => b
            [3] => bold
            [4] => </b>
        )

    [1] => Array
        (
            [0] => <a href="#">anchor</a>
            [1] => <a href="#">
            [2] => a
            [3] => anchor
            [4] => </a>
        )

)