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

Copy
1<?php
2
3declare(strict_types=1);
4
5/**
6 * ネットワークドライブ上のディレクトリを走り査し、指定した範囲のファイル名を出力します。
7 *
8 * この関数は、DirectoryIteratorとLimitIteratorを組み合わせて、
9 * ネットワーク上の共有フォルダ（UNCパス）にあるファイル一覧の一部を取得します。
10 * foreachループが内部でLimitIterator::next()を呼び出し、次の要素へ進みます。
11 *
12 * @param string $networkPath ネットワークドライブのUNCパス (例: '\\\\server\\share')
13 * @param int    $offset      一覧取得を開始するオフセット (0から始まる)
14 * @param int    $limit       取得するアイテムの最大数
15 * @return void
16 */
17function displayLimitedNetworkDirectory(string $networkPath, int $offset, int $limit): void
18{
19    // 注意: 実際にこのコードを実行するには、指定したネットワークパスへの
20    //       アクセス権限がPHPの実行ユーザーに必要です。
21    //       パスが存在しない、またはアクセスできない場合はエラーとなります。
22
23    echo "パス '{$networkPath}' の {$offset} 番目から {$limit} 個のアイテムを表示します。\n";
24    echo "----------------------------------------\n";
25
26    try {
27        // DirectoryIteratorは、指定されたパスのディレクトリ内のアイテムを反復処理します。
28        $directoryIterator = new DirectoryIterator($networkPath);
29
30        // LimitIteratorは、既存のイテレータをラップして、
31        // 指定した範囲（オフセットと個数）のアイテムのみを反復処理の対象とします。
32        $limitIterator = new LimitIterator($directoryIterator, $offset, $limit);
33
34        // foreach ループで LimitIterator を反復処理します。
35        // このループの各繰り返しで、LimitIterator::next() メソッドが内部的に自動で呼び出され、
36        // イテレータのポインタが次のファイルへと進みます。
37        foreach ($limitIterator as $fileInfo) {
38            echo $fileInfo->getFilename() . "\n";
39        }
40    } catch (UnexpectedValueException $e) {
41        // パスが見つからない場合やアクセスできない場合にスローされる例外を捕捉します。
42        echo "エラー: 指定されたパスにアクセスできませんでした。\n";
43        echo "詳細: " . $e->getMessage() . "\n";
44    } catch (Exception $e) {
45        echo "予期せぬエラーが発生しました: " . $e->getMessage() . "\n";
46    }
47
48    echo "----------------------------------------\n";
49}
50
51// --- 実行例 ---
52
53// アクセスしたいネットワークドライブのパスを指定します。
54// ※このパスはダミーです。ご自身の環境に合わせて有効なパスに変更してください。
55//   テスト用に、ローカルの既存ディレクトリパス（例: 'C:\\Windows' や '/tmp'）を指定することも可能です。
56$targetPath = '\\\\my-server\\public-share\\documents';
57
58// ディレクトリ一覧の3番目（オフセット=2）から5個のアイテムを取得して表示します。
59displayLimitedNetworkDirectory($targetPath, 2, 5);
60

LimitIterator::next()は、イテレータを次の要素に進めるためのメソッドです。このメソッドは引数を受け取らず、戻り値もありません。その役割は、イテレータが指している現在の位置を、リストの次の項目へと一つ進めることです。

サンプルコードでは、foreachループを使ってLimitIteratorオブジェクトを処理しています。このような場合、next()メソッドを直接呼び出す必要はありません。なぜなら、foreachループが次の要素へ移る際に、PHPの実行エンジンが内部で自動的にLimitIterator::next()を呼び出してくれるからです。

このコードは、まずDirectoryIteratorでネットワークドライブ上のディレクトリ情報を取得し、次にLimitIteratorでその中から指定した範囲（オフセットと個数）のファイルだけを対象としています。foreachループが実行されると、範囲内の最初のファイルが処理された後、内部でnext()が呼ばれて次のファイルへ移動します。この処理が指定した個数分繰り返されることで、結果的に特定の範囲のファイル名だけが出力される仕組みです。

Copy
1<?php
2
3/**
4 * LimitIterator::next() の使用例を示す関数
5 *
6 * LimitIteratorは、既存のイテレータの一部だけを反復処理するために使用します。
7 * next()メソッドは、イテレータを次の要素に進める役割を持ちます。
8 * 通常、foreachループ内で暗黙的に呼び出されますが、
9 * この例ではwhileループを使って手動で呼び出し、その動作を明確に示します。
10 */
11function demonstrateLimitIteratorNext(): void
12{
13    // 1. 元になるデータ配列を準備します
14    $fruits = [
15        'a' => 'Apple',
16        'b' => 'Banana',
17        'c' => 'Cherry',
18        'd' => 'Durian',
19        'e' => 'Elderberry',
20    ];
21
22    // 2. 配列からArrayIteratorオブジェクトを生成します
23    $arrayIterator = new ArrayIterator($fruits);
24
25    // 3. ArrayIteratorをラップするLimitIteratorを生成します
26    // オフセット1 (2番目の要素 'Banana') から、3つの要素を取得します
27    $limitIterator = new LimitIterator($arrayIterator, 1, 3);
28
29    // 4. whileループを使ってイテレータを手動で操作します
30    // rewind()でイテレータを対象範囲の先頭 (この場合は 'Banana') に移動します
31    $limitIterator->rewind();
32
33    while ($limitIterator->valid()) {
34        // 現在の要素が有効な間、ループを続けます
35
36        // 現在のキーと値を取得して表示します
37        echo sprintf(
38            "Key: %s, Value: %s\n",
39            $limitIterator->key(),
40            $limitIterator->current()
41        );
42
43        // next()メソッドを呼び出し、イテレータを次の要素に進めます
44        // これがこのサンプルの中心となる操作です
45        $limitIterator->next();
46    }
47}
48
49// 関数を実行して結果を表示します
50demonstrateLimitIteratorNext();
51
52/*
53実行結果:
54Key: b, Value: Banana
55Key: c, Value: Cherry
56Key: d, Value: Durian
57*/

PHPのLimitIterator::next()メソッドは、イテレータを次の要素へ進めるためのものです。このメソッドは引数を取らず、戻り値もありません。その役割は、イテレータが指し示している内部的な位置（カーソル）を一つ後ろに移動させることに特化しています。

サンプルコードでは、まずLimitIteratorクラスを使い、元の配列データの特定の部分（この例では2番目の要素から3つ分）だけを反復処理の対象としています。

通常foreach文を使う場合、next()メソッドはPHPによって裏側で自動的に呼び出されます。しかし、このサンプルではwhileループを用いて、イテレータの動きを意図的に一つずつ制御しています。ループの中では、valid()で要素の存在を確認し、current()で値を取得した後にnext()を呼び出すことで、手動でカーソルを次の要素へ進めています。このnext()の呼び出しによって、ループは次の要素へと進み、最終的にLimitIteratorで指定された範囲の全要素（'Banana', 'Cherry', 'Durian'）を順に処理することができます。