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

Copy
1<?php
2
3/**
4 * RecursiveCallbackFilterIterator の rewind 機能を実演します。
5 *
6 * このサンプルでは、多次元配列を再帰的にフィルタリングします。
7 * イテレータが foreach ループのたびに先頭に巻き戻る (rewind) ことを示すため、
8 * 同じイテレータで2回ループ処理を実行します。
9 *
10 * (通常のジェネレータは一度しかループできず、巻き戻し (rewind) できませんが、
11 *  RecursiveCallbackFilterIterator のような多くのイテレータは巻き戻し可能です)
12 */
13function demonstrateRewindableIterator(): void
14{
15    // 再帰的な処理の対象となる多次元配列
16    $data = [
17        'apple',
18        100,
19        ['orange', 200, 'grape'],
20        300,
21        ['nested' => [400, 'banana']],
22        'melon',
23    ];
24
25    // 再帰的な配列イテレータを作成
26    $arrayIterator = new RecursiveArrayIterator($data);
27
28    // 再帰的なコールバックフィルターイテレータを作成
29    // ここでは、現在の要素が整数 (int) の場合にのみ true を返すフィルターを定義
30    $filterIterator = new RecursiveCallbackFilterIterator(
31        $arrayIterator,
32        function ($current, $key, $iterator) {
33            // 子要素を持つ配列の場合は再帰的に探索を許可する
34            if ($iterator->hasChildren()) {
35                return true;
36            }
37            // 値が整数である要素のみを対象とする
38            return is_int($current);
39        }
40    );
41
42    // イテレータを再帰的に処理するためのイテレータ
43    $recursiveIterator = new RecursiveIteratorIterator($filterIterator);
44
45    echo "1回目のループ:\n";
46    // foreach は内部で最初に $recursiveIterator->rewind() を呼び出す
47    foreach ($recursiveIterator as $value) {
48        echo $value . "\n";
49    }
50
51    echo "\n";
52    echo "2回目のループ (同じイテレータインスタンスを使用):\n";
53    // 再度 foreach でループすると、再び内部で rewind() が呼び出され、
54    // イテレータが先頭に戻るため、同じ結果が出力される
55    foreach ($recursiveIterator as $value) {
56        echo $value . "\n";
57    }
58}
59
60// 関数を実行して結果を表示
61demonstrateRewindableIterator();
62

RecursiveCallbackFilterIteratorクラスのrewindメソッドは、イテレータを最初の要素に巻き戻す機能を提供します。このメソッドは引数を取らず、戻り値もありません（void）。その役割は、イテレータの内部的な位置を先頭に戻し、データセットを再度最初から走査できるようにリセットすることです。

このサンプルコードは、rewindメソッドの具体的な動作を示しています。まず、多次元配列を対象とし、値が整数である要素のみを抽出する再帰的なフィルターイテレータを作成します。PHPのforeachループは、処理を開始する際に、内部で自動的にイテレータのrewindメソッドを呼び出します。

コードでは、同じイテレータのインスタンスを使用して2回ループ処理を実行しています。2回目のループでも1回目と全く同じ結果が出力されるのは、ループが始まるたびにrewindメソッドによってイテレータの状態が先頭に巻き戻されるためです。このように、RecursiveCallbackFilterIteratorは「巻き戻し可能（rewindable）」な性質を持っており、一度走査を終えた後でも、再び最初からデータを処理できるという特徴があります。

Copy
1<?php
2
3/**
4 * RecursiveCallbackFilterIterator::rewind の動作を確認するサンプルコード
5 *
6 * rewind() メソッドは、イテレータを最初の要素に巻き戻します。
7 * このメソッドは、foreach ループが開始されるたびにPHPエンジンによって
8 * 内部的に自動で呼び出されるため、通常は開発者が直接呼び出す必要はありません。
9 *
10 * このサンプルでは、同じイテレータオブジェクトを使って2回 foreach ループを実行します。
11 * 2回目のループでも、イテレータが最初から正しく処理を開始することから、
12 * rewind() が暗黙的に呼び出されていることを確認できます。
13 */
14function demonstrateRewind(): void
15{
16    // 再帰的な構造を持つサンプル配列データ
17    $fileSystem = [
18        'documents' => [
19            'report.docx',
20            'specification.pdf',
21        ],
22        'images' => [
23            'logo.png',
24            'photo.jpg',
25        ],
26        'archive.zip',
27    ];
28
29    // 多次元配列を再帰的に走査するためのイテレータを作成
30    $arrayIterator = new RecursiveArrayIterator($fileSystem);
31
32    // フィルタリングのロジックを定義するコールバック関数
33    // この例では、拡張子が .pdf または .png の要素のみを許可します。
34    $filterCallback = function (string $current, string $key, RecursiveArrayIterator $iterator): bool {
35        // ディレクトリ（子を持つ要素）は常に走査対象とする
36        if ($iterator->hasChildren()) {
37            return true;
38        }
39        // ファイル（子を持たない要素）は、拡張子でフィルタリングする
40        return str_ends_with($current, '.pdf') || str_ends_with($current, '.png');
41    };
42
43    // コールバック関数を使ってフィルタリングを行うイテレータを作成
44    $filterIterator = new RecursiveCallbackFilterIterator($arrayIterator, $filterCallback);
45
46    // 再帰的なイテレータをフラットなリストとして扱うためのイテレータ
47    $recursiveIterator = new RecursiveIteratorIterator($filterIterator);
48
49    echo "1回目のループ処理:\n";
50    // foreach ループが開始されると、内部で rewind() が自動的に呼び出されます。
51    foreach ($recursiveIterator as $item) {
52        echo "- " . $item . "\n";
53    }
54
55    echo "\n";
56    echo "2回目のループ処理:\n";
57    // 再度 foreach ループを実行します。この際も、まず rewind() が呼び出され、
58    // イテレータが先頭に巻き戻されるため、1回目と全く同じ結果が得られます。
59    foreach ($recursiveIterator as $item) {
60        echo "- " . $item . "\n";
61    }
62}
63
64// 関数を実行して結果を表示
65demonstrateRewind();

RecursiveCallbackFilterIterator::rewind()は、イテレータの内部ポインタを最初の要素に巻き戻すためのメソッドです。このメソッドは引数を取らず、何も値を返しません（void）。その役割は、イテレータの状態を初期位置に戻すことだけに特化しています。

通常、開発者がこのメソッドを直接呼び出す必要はありません。なぜなら、foreach文でイテレータを処理する際に、ループの開始時点でPHPエンジンが内部的に自動で呼び出してくれるからです。

サンプルコードでは、特定の条件（拡張子が.pdfか.png）で配列要素をフィルタリングするイテレータを作成し、それを使ってforeachループを2回実行しています。1回目のループが終了した後、2回目のループが始まる際にも、PHPが自動的にrewind()メソッドを呼び出します。これによりイテレータが先頭に巻き戻されるため、2回目のループでも1回目と全く同じ結果が出力されます。この挙動から、rewind()がイテレータを再利用可能にするために重要な役割を果たしていることが分かります。