PHP Manual
Prev |  | Next

# preg_match_all

(PHP 3 >= 3.0.9, PHP 4, PHP 5)

preg_match_all -- Perform a global regular expression match

## Description

int preg_match_all ( string pattern, string subject, array &matches [, int flags [, int offset]] )

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`

  In this case, $matches[0] is the first set of matches, and `$matches[0][0]` has text matched by full pattern, `$matches[0][1]` has text matched by first subpattern and so on. Similarly, `$matches[1]` is the second set of matches, etc.

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

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

  `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 will also be returned. Note that this changes the value of `matches` in an array where every element is an array consisting of the matched string at offset `0` and its string offset into `subject` at offset `1`.

  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.

  > 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` if an error occurred.

## ChangeLog

Version | Description
--- | ---
4.3.3 | The `offset` parameter was added
4.3.0 | The `PREG_OFFSET_CAPTURE` flag was added

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

The above example will output:

    matched: <b>bold text</b>
    part 1: <b>
    part 2: bold text
    part 3: </b>

    matched: <a href=howdy.html>click me</a>
    part 1: <a href=howdy.html>
    part 2: click me
    part 3: </a>

## See Also

preg_match()
preg_replace()
preg_split()

Prev | Home | Next
preg_last_error | Up | preg_match