preg_match_all
(PHP 4, PHP 5, PHP 7, PHP 8)
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
-
以下のフラグの組み合わせ (
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 として通知されます。
flags
を指定しない場合は、PREG_PATTERN_ORDER
が指定されたことになります。 offset
-
通常、検索は対象文字列の先頭から開始されます。 オプションのパラメータ
offset
を使用して 検索の開始位置を (バイト単位で) 指定することも可能です。注意:
offset
を用いるのと、substr($subject, $offset)
を preg_match_all()の対象文字列として指定するのとは 等価ではありません。 これは、pattern
には、 ^, $ や (?<=x) のような言明を含めることができるためです。 これに関する例については、 preg_match() を参照ください。
戻り値
パターンがマッチした総数を返します(ゼロとなる可能性もあります)。
失敗した場合に false
を返します
エラー / 例外
渡された正規表現のパターンがコンパイルできない場合、E_WARNING
が発生します。
例
例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 正規表現処理のエラーコードを返す