繰り返し正規表現検索を行う

# preg_match_all

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

preg_match_all — 繰り返し正規表現検索を行う

### 説明

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

`subject` を検索し、 `pattern` に指定した正規表現にマッチした すべての文字列を、`flags` で指定した 順番で、`matches` に代入します。

正規表現にマッチすると、そのマッチした文字列の後から 検索が続行されます。

### パラメータ

`pattern`

  検索するパターンを表す文字列。

`subject`

  入力文字列。

`matches`

  マッチしたすべての内容を含む、 `flags` で指定した形式の多次元配列。

`flags`
  `flags` を指定しない場合は、 `PREG_PATTERN_ORDER` が指定されたことになります。

  以下のフラグの組み合わせ (`PREG_PATTERN_ORDER` と `PREG_SET_ORDER` を組み合わせて使用することは 意味をなさないので注意してください)。

  `PREG_PATTERN_ORDER`

    $matches[0] はパターン全体にマッチした文字列の配列、 $matches[1] は第 1 のキャプチャ用サブパターンにマッチした文字列の配列、 といった順番となります。

        <?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";
        ?>

    上の例の出力は以下となります。

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

    $out[0] はパターン全体にマッチした文字列の配列を有しており、 $out[1] はタグで囲まれた文字列の配列を有しています。

    パターンに名前付きサブパターンが含まれる場合は、$matches にはサブパターン名のキーも含まれるようになります。

    サブパターンの名前が重複している場合は、いちばん右側のサブパターンだけが $matches[NAME] に格納されます。

        <?php
        preg_match_all(
            '/(?J)(?<match>foo)|(?<match>bar)/',
            'foo bar',
            $matches,
            PREG_PATTERN_ORDER
        );
        print_r($matches['match']);
        ?>

    上の例の出力は以下となります。

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

  `PREG_SET_ORDER`

    $matches[0] は 1 回目のマッチングでキャプチャした値の配列、 $matches[1] は 2 回目のマッチングでキャプチャした値の配列、 といった順序となります。

        <?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";
        ?>

    上の例の出力は以下となります。

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

  `PREG_OFFSET_CAPTURE`

    このフラグを設定した場合、各マッチに対応する文字列のオフセットも(バイト単位で)返されます。 これは、`matches` の値を配列の配列の配列に変更することに注意してください。 配列の要素である配列のすべての要素が、オフセット `0` に、マッチした文字列、 オフセット `1` に、`subject` 内でのその文字列のオフセット からなる配列になります。

        <?php
        preg_match_all('/(foo)(bar)(baz)/', 'foobarbaz', $matches, PREG_OFFSET_CAPTURE);
        print_r($matches);
        ?>

    上の例の出力は以下となります。

        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`

    このフラグを設定すると、サブパターンがマッチしなかった場合に `null` が渡されます。 通常は、空の string が渡されます。

`offset`

  通常、検索は対象文字列の先頭から開始されます。 オプションのパラメータ `offset` を使用して 検索の開始位置を (バイト単位で) 指定することも可能です。

  > 注意:

  > `offset` を用いるのと、 `substr($subject, $offset)` を preg_match_all()の対象文字列として指定するのとは 等価ではありません。 これは、`pattern` には、 ^, $ や (?<=x) のような言明を含めることができるためです。 これに関する例については、 preg_match() を参照ください。

### 戻り値

パターンがマッチした総数を返します（ゼロとなる可能性もあります）。 失敗した場合に `false` を返します

### エラー / 例外

渡された正規表現のパターンがコンパイルできない場合、`E_WARNING` が発生します。

### 変更履歴

バージョン | 説明
--- | ---
7.2.0 | `$flags` パラメータが `PREG_UNMATCHED_AS_NULL` をサポートしました。

### 例

例1 テキストからすべての電話番号を得る

    <?php
    preg_match_all("/\(?  (\d{3})?  \)?  (?(1)  [\-\s] ) \d{3}-\d{4}/x",
                    "Call 555-1212 or 1-800-555-1212", $phones);
    ?>

例2 HTML タグにマッチするものを見付ける（貪欲）

    <?php
    // \\2 は後方参照の例。これは、pcre に正規表現中の括弧の 2 番目の
    // 組、つまりこの場合は ([\w]+)、にマッチする。文字列が二重引用符で
    // 括られているため、バックスラッシュの追加が必要。
    $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";
    }
    ?>

上の例の出力は以下となります。

    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>

例3 名前つきサブパターンの使用法

    <?php

    $str = <<<FOO
    a: 1
    b: 2
    c: 3
    FOO;

    preg_match_all('/(?P<name>\w+): (?P<digit>\d+)/', $str, $matches);

    /* 別のやり方 */
    // preg_match_all('/(?<name>\w+): (?<digit>\d+)/', $str, $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
            )

    )

### 参考

- PCRE のパターン
- preg_quote() - 正規表現文字をクオートする
- preg_match() - 正規表現によるマッチングを行う
- preg_replace() - 正規表現検索および置換を行う
- preg_split() - 正規表現で文字列を分割する
- preg_last_error() - 直近の PCRE 正規表現処理のエラーコードを返す

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