【PHP8.x】RegexIterator::setPregFlags()メソッドの使い方

setPregFlagsメソッドの使い方について、初心者にもわかりやすく解説します。

作成日: 2025年09月11日更新日: 2025年12月24日

基本的な使い方

setPregFlagsメソッドは、RegexIteratorオブジェクトが使用する正規表現のフラグを設定または変更するために実行するメソッドです。RegexIteratorは、イテレータの各要素を正規表現パターンでフィルタリングする際に、内部でPerl互換の正規表現関数（PCRE関数）を使用します。このメソッドは、その正規表現関数のマッチング動作を細かく制御するためのオプション（フラグ）を、オブジェクトの生成後に指定する機能を提供します。引数には、PREG_で始まる定数を整数値として渡します。例えば、PREG_OFFSET_CAPTUREフラグを設定すると、マッチした文字列に加えて、その文字列が元のデータ内のどの位置（オフセット）から始まるかの情報も取得できるようになります。同様に、PREG_UNMATCHED_AS_NULLフラグを使用すると、マッチしなかったサブパターンの結果を空文字列ではなくNULLとして扱うように動作を変更できます。これらのフラグはRegexIteratorのコンストラクタでも指定できますが、本メソッドを用いることで、インスタンス化された後から動的に検索条件を調整することが可能になります。このメソッドに戻り値はありません。

構文(syntax)


1<?php
2
3// 操作対象となるイテレータを作成します。
4$arrayIterator = new ArrayIterator(['Test 1', 'Test 2', 'Skip 3']);
5
6// 正規表現パターンに一致する要素をフィルタリングするイテレータを作成します。
7$regexIterator = new RegexIterator($arrayIterator, '/(Test)\s(\d)/', RegexIterator::GET_MATCH);
8
9// preg フラグを設定する構文です。
10// この例では PREG_OFFSET_CAPTURE を設定し、マッチした文字列のオフセット位置も取得します。
11$regexIterator->setPregFlags(PREG_OFFSET_CAPTURE);
12
13// 結果をイテレーションして表示します。
14foreach ($regexIterator as $match) {
15    print_r($match);
16}
17
18?>

引数(parameters)

int $flags

int $flags: 正規表現の検索に使用するフラグを指定する整数

戻り値(return)

戻り値なし

戻り値はありません

サンプルコード

PHP RegexIterator の setPregFlags によるマッチ結果の並び替え


1<?php
2
3/**
4 * RegexIterator::setPregFlags の使用例を示します。
5 * RegexIterator は、イテレータをフィルタリングし、正規表現にマッチする要素のみを処理します。
6 * setPregFlags メソッドは、RegexIterator が内部で正規表現マッチングを行う際に使用されるフラグを設定します。
7 * 特に RegexIterator::GET_MATCH モードと組み合わせることで、
8 * preg_match_all の結果の配列形式（PREG_PATTERN_ORDER と PREG_SET_ORDER）に影響を与えます。
9 *
10 * @see https://www.php.net/manual/ja/regexiterator.setpregflags.php
11 * @see https://www.php.net/manual/ja/function.preg-match-all.php
12 */
13function demonstrateRegexIteratorPregFlags(): void
14{
15    // 対象となる文字列の配列。
16    // 各文字列に複数の「単語と単語」の組み合わせが含まれるようにし、
17    // PREG_PATTERN_ORDER と PREG_SET_ORDER の違いを明確にします。
18    $data = [
19        "apple pie and cherry tart is delicious",
20        "banana split and date shake is sweet"
21    ];
22
23    // ArrayIterator を作成し、元のデータをイテレータとして利用可能にする
24    $arrayIterator = new ArrayIterator($data);
25
26    // 正規表現パターン: 連続する2つの単語をキャプチャ (例: "apple pie", "cherry tart")
27    $pattern = '/(\w+)\s(\w+)/';
28
29    // RegexIterator を作成
30    // 第一引数: 基本となるイテレータ (ArrayIterator)
31    // 第二引数: 正規表現パターン
32    // 第三引数: モード (RegexIterator::ALL_MATCHES を指定すると、
33    //               preg_match_all のように各要素からすべてのマッチを抽出します)
34    $regexIterator = new RegexIterator($arrayIterator, $pattern, RegexIterator::ALL_MATCHES);
35
36    // RegexIterator::setMode() を使用して、イテレータが元の値ではなく、
37    // 正規表現のマッチ結果（preg_match_all の $matches 配列に相当）を返すように設定します。
38    // これを設定しないと setPregFlags の効果が分かりにくいため、必須です。
39    $regexIterator->setMode(RegexIterator::GET_MATCH);
40
41    echo "--- setPregFlags(PREG_PATTERN_ORDER) の場合 ---" . PHP_EOL . PHP_EOL;
42
43    // setPregFlags を使用して PREG_PATTERN_ORDER フラグを設定
44    // PREG_PATTERN_ORDER は、preg_match_all のデフォルトの動作を模倣し、
45    // 結果の配列が「パターン順」になります。
46    // 例: [ [全体マッチ1, 全体マッチ2, ...], [グループ1マッチ1, グループ1マッチ2, ...], ... ]
47    $regexIterator->setPregFlags(PREG_PATTERN_ORDER);
48
49    // イテレータをループして結果を表示
50    foreach ($regexIterator as $originalStringKey => $matches) {
51        // $matches は、ArrayIterator の元の1つの文字列に対する preg_match_all の結果です。
52        echo "元のデータキー [" . $originalStringKey . "]: \"" . $data[$originalStringKey] . "\"" . PHP_EOL;
53        // マッチした文字列全体の結果を表示
54        echo "  マッチした文字列全体: " . (isset($matches[0]) ? implode(" | ", $matches[0]) : "N/A") . PHP_EOL;
55        // キャプチャグループ1の結果を表示
56        if (isset($matches[1])) {
57            echo "  キャプチャグループ1: " . implode(" | ", $matches[1]) . PHP_EOL;
58        }
59        // キャプチャグループ2の結果を表示
60        if (isset($matches[2])) {
61            echo "  キャプチャグループ2: " . implode(" | ", $matches[2]) . PHP_EOL;
62        }
63        echo PHP_EOL;
64    }
65
66    echo "--- setPregFlags(PREG_SET_ORDER) の場合 ---" . PHP_EOL . PHP_EOL;
67
68    // setPregFlags を使用して PREG_SET_ORDER フラグを設定
69    // PREG_SET_ORDER は、結果の配列が「マッチ順」になります。
70    // 例: [ [全体マッチ1, グループ1マッチ1, グループ2マッチ1, ...], [全体マッチ2, グループ1マッチ2, グループ2マッチ2, ...], ... ]
71    $regexIterator->setPregFlags(PREG_SET_ORDER);
72
73    // イテレータをループして結果を表示
74    foreach ($regexIterator as $originalStringKey => $matches) {
75        // $matches は、ArrayIterator の元の1つの文字列に対する preg_match_all の結果です。
76        echo "元のデータキー [" . $originalStringKey . "]: \"" . $data[$originalStringKey] . "\"" . PHP_EOL;
77        foreach ($matches as $matchIndex => $matchSet) {
78            echo "  マッチセット " . ($matchIndex + 1) . ":" . PHP_EOL;
79            echo "    全体マッチ: " . (isset($matchSet[0]) ? $matchSet[0] : "N/A") . PHP_EOL;
80            // キャプチャグループ1の結果を表示
81            if (isset($matchSet[1])) {
82                echo "    グループ1: " . $matchSet[1] . PHP_EOL;
83            }
84            // キャプチャグループ2の結果を表示
85            if (isset($matchSet[2])) {
86                echo "    グループ2: " . $matchSet[2] . PHP_EOL;
87            }
88        }
89        echo PHP_EOL;
90    }
91}
92
93// 関数を実行して、RegexIterator::setPregFlags の動作を確認
94demonstrateRegexIteratorPregFlags();

PHPのRegexIterator::setPregFlagsメソッドは、イテレータを正規表現でフィルタリングするRegexIteratorクラスに、内部で利用される正規表現マッチングの動作を制御するフラグを設定します。

このメソッドの引数$flagsには、PHPのpreg_match_all関数で使用されるPREG_PATTERN_ORDERやPREG_SET_ORDERといった定数を整数値で指定します。これらのフラグは、正規表現で複数のマッチが見つかった際に、その結果がどのような配列形式で格納されるかを決定します。このメソッドは戻り値を持ちません。

サンプルコードでは、RegexIterator::GET_MATCHモードと組み合わせてこのフラグの効果を具体的に示しています。PREG_PATTERN_ORDERを設定した場合、正規表現のマッチ結果は、すべての全体マッチ、すべてのキャプチャグループ1のマッチ、というように、グループごとにまとまった形式で返されます。対照的に、PREG_SET_ORDERを設定すると、1つ目の全体マッチとそのキャプチャグループ、2つ目の全体マッチとそのキャプチャグループ、というように、個々のマッチセットごとに結果がまとめられた形式で返されます。これにより、正規表現で取得した複数のマッチ結果を、目的に応じて異なる配列構造で取得できることを理解できます。

setPregFlagsメソッドは、RegexIterator::GET_MATCHモードと組み合わせて利用すると、その効果が明確になります。このメソッドの引数には、内部で使用されるpreg_match_all関数の結果配列の形式を制御するフラグ（PREG_PATTERN_ORDERやPREG_SET_ORDERなど）を整数で渡します。PREG_PATTERN_ORDERはキャプチャグループごとにマッチ結果をまとめ、PREG_SET_ORDERはマッチした要素ごとに結果をまとめます。このフラグ設定により、イテレータから取得できる配列の構造が大きく変わるため、その後のデータ処理コードも適切に調整する必要がある点にご注意ください。戻り値がないため、メソッドチェーンには利用できません。

PHP RegexIterator で正規表現フラグを設定する


1<?php
2
3/**
4 * RegexIterator::setPregFlags の使用例を示します。
5 * このメソッドは、内部的に使用される正規表現関数 (preg_grep, preg_match_all など) に渡すフラグを設定します。
6 * PREG_GREP_INVERT フラグを使用すると、正規表現にマッチしない要素をフィルタリングできます。
7 */
8
9// 検索対象となるデータ（配列）
10$data = [
11    'apple',
12    'banana',
13    'apricot',
14    'orange',
15    'grape',
16    'pineapple',
17];
18
19// ArrayIterator を使用して、配列をイテレータに変換します。
20$arrayIterator = new ArrayIterator($data);
21
22// 正規表現パターン: 'a' で始まる文字列
23$pattern = '/^a/';
24
25// RegexIterator を作成します。
26// RegexIterator::MATCH モードは、正規表現にマッチする要素のみを返します。
27$regexIterator = new RegexIterator($arrayIterator, $pattern, RegexIterator::MATCH);
28
29echo "--- 元の RegexIterator の結果 (パターン '/^a/' にマッチするもの) ---\n";
30// ループでイテレートし、マッチした要素を表示します。
31foreach ($regexIterator as $value) {
32    echo "マッチ: " . $value . "\n";
33}
34echo "\n";
35
36// setPregFlags() を使用して、正規表現のフラグを設定します。
37// ここでは PREG_GREP_INVERT を設定し、マッチしない要素を返すようにします。
38$regexIterator->setPregFlags(PREG_GREP_INVERT);
39
40echo "--- setPregFlags(PREG_GREP_INVERT) 設定後の結果 (パターン '/^a/' にマッチしないもの) ---\n";
41// 再度ループでイテレートし、フラグ変更後の結果を表示します。
42foreach ($regexIterator as $value) {
43    echo "マッチしない: " . $value . "\n";
44}
45
46?>

PHPのRegexIterator::setPregFlagsメソッドは、RegexIteratorが内部的に正規表現の処理を行う際に、その動作を制御するための追加フラグを設定するものです。このメソッドは、整数型の$flagsという引数を一つ取ります。この引数には、例えばPREG_GREP_INVERTのような特定の定数を指定することで、正規表現のマッチング挙動を変更できます。このメソッドは、値を返しません。

サンプルコードでは、まずRegexIteratorを用いて、配列の中から正規表現/^a/（「a」で始まる文字列）にマッチする要素（apple、apricot、pineapple）を抽出しています。

その次に、$regexIterator->setPregFlags(PREG_GREP_INVERT);を呼び出しています。ここでPREG_GREP_INVERTフラグを設定すると、RegexIteratorの動作が反転し、今度は正規表現に「マッチしない」要素を返すようになります。そのため、設定後に再度ループを回すと、「a」で始まらないbanana、orange、grapeが表示される結果となります。

このようにsetPregFlagsメソッドを利用することで、同じ正規表現パターンを使いながらも、マッチング条件を柔軟に切り替え、マッチする要素を抽出するだけでなく、マッチしない要素を除外・抽出するといった応用的なフィルタリングが可能になります。

setPregFlagsメソッドは、RegexIteratorが内部で使用する正規表現関数の挙動を制御します。引数にはPREG_GREP_INVERTのようなPHPの正規表現定数を指定し、複数のフラグはビット演算子|で組み合わせられます。このメソッドを呼び出すと、その後のイテレーション結果に影響を与えるため、フラグ変更後に再度イテレートする際は結果が変化することを理解しておきましょう。特にPREG_GREP_INVERTは、正規表現にマッチする要素ではなく、マッチしない要素を返すように動作を反転させます。意図しないフィルタリングを避けるため、適用後の動作を必ず確認することが重要です。戻り値がないため、設定の成否はイテレーション結果で確認します。