Perform a global regular expression match

# preg_match_all

(PHP 4, PHP 5, PHP 7, PHP 8)

preg_match_all — Perform a global regular expression match

### Description

preg_match_all(
string `$pattern`,
string `$subject`,
array `&$matches` = `null`,
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`
  If no order flag is given, `PREG_PATTERN_ORDER` is assumed.

  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:

        <b>example: </b>, <div align=left>this is a test</div>
        example: , this is a test

    So, $out[0] contains an array of strings that matched the full pattern, and $out[1] contains an 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:

        <b>example: </b>, example:
        <div align="left">this is a test</div>, 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.

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

### Errors/Exceptions

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.

### 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] . "\n";
echo "part 1: " . $val[1] . "\n";
echo "part 2: " . $val[2] . "\n";
echo "part 3: " . $val[3] . "\n";
echo "part 4: " . $val[4] . "\n\n";
}
?>`

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);
/* Alternative */
// 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() - Quote regular expression characters
- preg_match() - Perform a regular expression match
- preg_replace() - Perform a regular expression search and replace
- preg_split() - Split string by a regular expression
- preg_last_error() - Returns the error code of the last PCRE regex execution

`↑` and `↓` to navigate • `Enter` to select • `Esc` to close • `/` to open