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

Copy
1<?php
2
3/**
4 * RecursiveDirectoryIterator::seek メソッドの使用例を示します。
5 * このメソッドは、現在のディレクトリ内の指定されたオフセット（位置）にイテレータを移動させます。
6 * PHP 8 を想定しています。
7 */
8function demonstrateRecursiveDirectoryIteratorSeek(): void
9{
10    // 一時ディレクトリの名前を定義し、一意のIDを付与して衝突を避けます。
11    $testDir = sys_get_temp_dir() . DIRECTORY_SEPARATOR . 'php_seek_test_' . uniqid();
12
13    // テスト用のディレクトリとファイルを作成します。
14    // mkdir() は成功時に true、失敗時に false を返します。
15    // is_dir() でディレクトリが実際に作成されたかを確認します。
16    if (!mkdir($testDir) && !is_dir($testDir)) {
17        throw new \RuntimeException(sprintf('Directory "%s" was not created', $testDir));
18    }
19
20    // いくつかのテストファイルとサブディレクトリを作成します。
21    // これらはイテレータが走査する対象となります。
22    file_put_contents($testDir . DIRECTORY_SEPARATOR . 'file_a.txt', 'Content A');
23    file_put_contents($testDir . DIRECTORY_SEPARATOR . 'file_b.txt', 'Content B');
24    mkdir($testDir . DIRECTORY_SEPARATOR . 'subdir_c'); // これはディレクトリとして扱われます
25    file_put_contents($testDir . DIRECTORY_SEPARATOR . 'file_d.txt', 'Content D');
26
27    echo "--- 準備されたファイルシステム --- \n";
28    echo "ルートディレクトリ: " . basename($testDir) . "\n";
29    echo "  - file_a.txt\n";
30    echo "  - file_b.txt\n";
31    echo "  - subdir_c (ディレクトリ)\n";
32    echo "  - file_d.txt\n";
33    echo "---------------------------------\n\n";
34
35    try {
36        // RecursiveDirectoryIterator を作成します。
37        // FilesystemIterator::SKIP_DOTS: "." と ".." ディレクトリをスキップし、
38        //   実際のファイルやディレクトリのみをオフセットのカウント対象とします。
39        // FilesystemIterator::UNIX_PATHS: パスの区切り文字を '/' に統一します。
40        $iterator = new RecursiveDirectoryIterator(
41            $testDir,
42            FilesystemIterator::SKIP_DOTS | FilesystemIterator::UNIX_PATHS
43        );
44
45        echo "イテレータの初期状態（rewind()後）:\n";
46        // rewind() でイテレータを先頭（オフセット0）にリセットします。
47        $iterator->rewind();
48        // current() で現在の要素を取得し、getFilename() でファイル名を表示します。
49        // このディレクトリでは通常 'file_a.txt' が最初の要素になります。
50        echo "  現在位置 (0): " . $iterator->current()->getFilename() . "\n\n";
51
52        echo "seek(2) で3番目の要素に移動:\n";
53        // seek(2) でイテレータを3番目の要素（インデックス2）に移動させます。
54        // このディレクトリでは 'file_a.txt' (0), 'file_b.txt' (1), 'subdir_c' (2) となります。
55        $iterator->seek(2);
56        echo "  移動後 (2): " . $iterator->current()->getFilename() . "\n\n";
57
58        echo "seek(0) で再び先頭に戻る:\n";
59        // seek(0) でイテレータを最初の要素（インデックス0）に戻します。
60        $iterator->seek(0);
61        echo "  移動後 (0): " . $iterator->current()->getFilename() . "\n\n";
62
63        echo "seek(3) で4番目の要素に移動:\n";
64        // seek(3) でイテレータを4番目の要素（インデックス3）に移動させます。
65        // このディレクトリでは 'file_a.txt' (0), 'file_b.txt' (1), 'subdir_c' (2), 'file_d.txt' (3) となります。
66        $iterator->seek(3);
67        echo "  移動後 (3): " . $iterator->current()->getFilename() . "\n\n";
68
69        // 存在しないオフセットへの seek は OutOfBoundsException を発生させます。
70        // 初心者向けに簡潔さを保つため、ここではエラーハンドリングの例はコメントアウトします。
71        // echo "存在しないオフセットへの seek の試行 (OutOfBoundsException):\n";
72        // try {
73        //     $iterator->seek(100); // 存在しないインデックス
74        //     echo "  移動後 (100): " . $iterator->current()->getFilename() . "\n\n";
75        // } catch (OutOfBoundsException $e) {
76        //     echo "  エラー: " . $e->getMessage() . "\n\n";
77        // }
78
79    } finally {
80        // テスト用ディレクトリとファイルをクリーンアップします。
81        // RecursiveIteratorIterator を使用して、サブディレクトリも含め再帰的に削除します。
82        echo "--- クリーンアップ --- \n";
83        $rdi = new RecursiveDirectoryIterator($testDir, FilesystemIterator::SKIP_DOTS);
84        $rii = new RecursiveIteratorIterator($rdi, RecursiveIteratorIterator::CHILD_FIRST);
85        foreach ($rii as $fileinfo) {
86            if ($fileinfo->isDir()) {
87                rmdir($fileinfo->getRealPath()); // ディレクトリの場合、rmdir で削除
88            } else {
89                unlink($fileinfo->getRealPath()); // ファイルの場合、unlink で削除
90            }
91        }
92        rmdir($testDir); // 最上位のテストディレクトリを削除
93        echo "テスト用ディレクトリ '" . basename($testDir) . "' を削除しました。\n";
94        echo "---------------------- \n";
95    }
96}
97
98// サンプルコードを実行します。
99demonstrateRecursiveDirectoryIteratorSeek();

PHP 8のRecursiveDirectoryIterator::seekメソッドは、ディレクトリ内のファイルやサブディレクトリといった要素を順番に処理するイテレータの現在位置を、指定したオフセット（位置）に直接移動させる機能を提供します。このメソッドが利用できるのは、RecursiveDirectoryIteratorクラスがSeekableIteratorインターフェースを実装しているためです。

引数$offsetには、移動したい要素の0から始まるインデックスを整数で指定します。例えば、seek(0)は最初の要素へ、seek(2)は3番目の要素へイテレータを移動させます。このメソッドはイテレータの内部的な位置を変更するだけで、特に値を返すことはありません（戻り値はなし）。

サンプルコードでは、一時的に作成されたディレクトリ内のファイルとサブディレクトリを対象にRecursiveDirectoryIteratorを作成し、FilesystemIterator::SKIP_DOTSフラグを使用して.や..といった特殊なディレクトリをオフセットのカウントから除外しています。イテレータをrewind()で先頭にリセットした後、seek(2)で3番目の要素である「subdir_c」へ移動し、そのファイル名を表示します。さらにseek(0)で再び最初の要素「file_a.txt」へ、seek(3)で4番目の要素「file_d.txt」へと移動する様子が示されており、イテレータがディレクトリ内の任意の要素へ瞬時にジャンプできることが分かります。

Copy
1<?php
2
3/**
4 * RecursiveDirectoryIterator::seek メソッドの使用方法をデモンストレーションします。
5 *
6 * システムエンジニアを目指す初心者向けに、指定されたオフセットにイテレータを移動させ、
7 * 特に「seek_end」の概念（ディレクトリ内の最後の要素への移動）を実演します。
8 */
9function demonstrateRecursiveDirectoryIteratorSeek(): void
10{
11    // --- 1. セットアップ: テスト用のディレクトリとファイルを作成 ---
12    $testDirPath = sys_get_temp_dir() . '/recursive_dir_seek_test_' . uniqid('php_seek_', true);
13    if (!mkdir($testDirPath) && !is_dir($testDirPath)) {
14        throw new RuntimeException(sprintf('Directory "%s" was not created', $testDirPath));
15    }
16    file_put_contents($testDirPath . '/file_a.txt', 'Content A');
17    file_put_contents($testDirPath . '/file_b.txt', 'Content B');
18    file_put_contents($testDirPath . '/file_c.txt', 'Content C');
19    // サブディレクトリも作成しますが、RecursiveDirectoryIterator::seek は現在のディレクトリレベルで動作することを示すため、
20    // まずはルートディレクトリ内のファイルでseekを実演します。
21    mkdir($testDirPath . '/subdir');
22    file_put_contents($testDirPath . '/subdir/subfile_x.txt', 'Sub Content X');
23
24    echo "テストディレクトリを作成しました: " . $testDirPath . "\n\n";
25
26    try {
27        // --- 2. RecursiveDirectoryIteratorの初期化 ---
28        // RecursiveDirectoryIterator は、指定されたディレクトリ内のエントリ（ファイルやサブディレクトリ）をイテレートします。
29        // seek メソッドは、現在のディレクトリレベルでのみ動作し、再帰的な全体構造には影響しません。
30        $iterator = new RecursiveDirectoryIterator($testDirPath);
31        echo "RecursiveDirectoryIterator を初期化しました。\n";
32
33        // --- 3. ディレクトリ内の要素を一度走査し、総数と最後の要素のインデックスを把握 ---
34        // RecursiveDirectoryIterator::seek は絶対オフセットを取るため、
35        // 「seek_end」（最後の要素への移動）を実現するには、事前に要素の総数を把握する必要があります。
36        $totalItems = 0;
37        $lastItemIndex = -1;
38        $lastItemName = '';
39
40        echo "--- 初期走査 (要素の数と最後のインデックスを把握) ---\n";
41        foreach ($iterator as $index => $fileinfo) {
42            echo sprintf("検出: インデックス %d, ファイル名: %s\n", $index, $fileinfo->getFilename());
43            $totalItems++;
44            $lastItemIndex = $index; // 最後に走査されたインデックスが最終インデックス
45            $lastItemName = $fileinfo->getFilename();
46        }
47        echo sprintf("\nディレクトリ内の合計アイテム数 (初期走査): %d\n", $totalItems);
48        if ($totalItems > 0) {
49            echo sprintf("最後のアイテムのインデックス: %d (ファイル名: %s)\n\n", $lastItemIndex, $lastItemName);
50        } else {
51            echo "ディレクトリは空です。\n\n";
52        }
53
54        if ($totalItems > 0) {
55            // --- 4. seek(0) でイテレータを先頭に移動 ---
56            echo "--- seek(0): イテレータを先頭に移動 ---\n";
57            $iterator->seek(0); // seek(0) はイテレータを最初の要素に移動させます。
58            if ($iterator->valid()) {
59                echo sprintf("現在の要素 (seek(0)): %s\n\n", $iterator->current()->getFilename());
60            } else {
61                echo "seek(0)後、イテレータが無効です。通常は発生しません。\n\n";
62            }
63
64            // --- 5. seek($lastItemIndex) で末尾（最後の要素）に移動 ---
65            // キーワード「seek_end」に最も関連性の高い動作です。
66            // 既に把握した最後の要素のインデックスを使用します。
67            echo sprintf("--- seek_end: 最後の要素に移動 (seek(%d)) ---\n", $lastItemIndex);
68            // seek を使用する前に、イテレータが有効な状態であることを確認するか、
69            // rewind() で先頭に戻してから seek すると、より確実に指定位置に移動できます。
70            $iterator->rewind();
71            $iterator->seek($lastItemIndex);
72            if ($iterator->valid()) {
73                echo sprintf("現在の要素 (seek_end): %s\n\n", $iterator->current()->getFilename());
74            } else {
75                echo "seek_end後、イテレータが無効です。これは最後の要素を超えてseekした場合に発生しえます。\n\n";
76            }
77        } else {
78            echo "ディレクトリが空のため、seek 操作を実演できません。\n\n";
79        }
80
81    } catch (UnexpectedValueException $e) {
82        // RecursiveDirectoryIterator は、指定されたパスが無効な場合にこの例外をスローすることがあります。
83        echo "エラー: " . $e->getMessage() . "\n";
84    } finally {
85        // --- 6. クリーンアップ: テスト用ディレクトリとファイルを削除 ---
86        if (file_exists($testDirPath)) {
87            // RecursiveIteratorIterator を使用してディレクトリ内のすべてのファイルとサブディレクトリを再帰的に削除します。
88            $files = new RecursiveIteratorIterator(
89                new RecursiveDirectoryIterator($testDirPath, RecursiveDirectoryIterator::SKIP_DOTS),
90                RecursiveIteratorIterator::CHILD_FIRST
91            );
92            foreach ($files as $fileinfo) {
93                if ($fileinfo->isDir()) {
94                    rmdir($fileinfo->getRealPath());
95                } else {
96                    unlink($fileinfo->getRealPath());
97                }
98            }
99            rmdir($testDirPath);
100            echo "テストディレクトリとファイルをクリーンアップしました。\n";
101        }
102    }
103}
104
105// スクリプトの実行
106demonstrateRecursiveDirectoryIteratorSeek();
107
108?>

PHPのRecursiveDirectoryIterator::seekメソッドは、ディレクトリ内のファイルやサブディレクトリといった要素を巡回するイテレータの現在位置を、指定した絶対オフセットに直接移動させる機能を提供します。引数int $offsetには、移動したい要素の0から始まるインデックスを渡します。例えば、seek(0)とするとイテレータは最初の要素に移動します。このメソッドは戻り値を持ちませんが、呼び出し後にイテレータの現在位置が変更されます。

サンプルコードでは「seek_end」という概念を実演しており、これはイテレータをディレクトリ内の最後の要素に移動させる操作を指します。RecursiveDirectoryIterator::seekメソッド自体に「末尾へ移動」という直接的な機能はありませんが、事前にディレクトリ内の要素の総数を把握し、その最後の要素のインデックスをseekメソッドに渡すことで、末尾への移動を実現しています。この機能は、大量のファイルの中から特定のインデックスのファイルに直接アクセスしたい場合などに役立ちます。