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

Copy
1<?php
2
3/**
4 * 指定されたディレクトリの内容を走査し、ファイルとディレクトリを一覧表示します。
5 * この関数は、Webサーバーなどのネットワークサービスが、自身のホスト上で
6 * 特定のディレクトリ内のファイルを管理・表示する際の基本的な操作を示します。
7 * DirectoryIterator::next() メソッドを使用して、明示的に次のエントリへ進みます。
8 *
9 * @param string $directoryPath 走査するディレクトリのパス
10 * @return void
11 */
12function listDirectoryContents(string $directoryPath): void
13{
14    // ディレクトリが存在しないか、読み取り可能でない場合はエラーメッセージを表示して終了します。
15    if (!is_dir($directoryPath) || !is_readable($directoryPath)) {
16        echo "エラー: ディレクトリ '{$directoryPath}' が存在しないか、読み取りできません。\n";
17        return;
18    }
19
20    echo "ディレクトリ '{$directoryPath}' の内容:\n";
21    echo "----------------------------------------\n";
22
23    try {
24        // DirectoryIterator のインスタンスを作成します。
25        // これにより、指定されたディレクトリの内容を反復処理できるようになります。
26        $iterator = new DirectoryIterator($directoryPath);
27
28        // イテレータのポインタを先頭に戻します。
29        // (DirectoryIterator は通常、インスタンス化時に先頭に設定されますが、
30        // 明示的に呼び出すことで、処理を最初から開始することを保証できます。)
31        $iterator->rewind();
32
33        // ポインタが有効なエントリを指している間、ループを続けます。
34        while ($iterator->valid()) {
35            // '.' と '..' は現在のディレクトリと親ディレクトリを表す特殊なエントリです。
36            // 通常、これらは一覧表示から除外します。
37            if ($iterator->isDot()) {
38                // 次のエントリにポインタを進め、現在のループ処理をスキップします。
39                $iterator->next();
40                continue;
41            }
42
43            // 現在のエントリがディレクトリであるかチェックします。
44            if ($iterator->isDir()) {
45                echo "[D] " . $iterator->getFilename() . "\n";
46            }
47            // 現在のエントリがファイルであるかチェックします。
48            elseif ($iterator->isFile()) {
49                echo "[F] " . $iterator->getFilename() . " (" . $iterator->getSize() . " bytes)\n";
50            }
51            // その他のタイプのエントリ（シンボリックリンクなど）の場合。
52            else {
53                echo "[?] " . $iterator->getFilename() . "\n";
54            }
55
56            // 次のエントリにポインタを進めます。
57            // これが DirectoryIterator::next() メソッドの利用例です。
58            $iterator->next();
59        }
60        echo "----------------------------------------\n";
61
62    } catch (UnexpectedValueException $e) {
63        // 無効なディレクトリパスが渡された場合など、DirectoryIteratorのコンストラクタが
64        // 例外を投げる可能性があります。
65        echo "エラー: ディレクトリの読み込み中に問題が発生しました - " . $e->getMessage() . "\n";
66    }
67}
68
69// このスクリプトが実行されている現在のディレクトリを対象として、関数を呼び出します。
70// 実際のシステムでは、Webアプリケーションのアップロードディレクトリやログディレクトリなど、
71// ネットワークサービスがアクセスする特定のパスを指定することが考えられます。
72$targetDirectory = __DIR__;
73listDirectoryContents($targetDirectory);
74

PHPのDirectoryIterator::next()メソッドは、ディレクトリの内容を順に走査する際に利用される重要なメソッドです。このメソッドはDirectoryIteratorクラスに属し、指定されたディレクトリ内のファイルやサブディレクトリを一つずつ処理するために、現在の参照位置（ポインタ）を次のエントリへ移動させる役割を担います。引数はなく、処理の結果として直接的な戻り値もありません。内部的にイテレータの状態を更新するだけのシンプルな操作です。

提供されたサンプルコードでは、listDirectoryContents関数が特定のディレクトリの内容を一覧表示する際に、このnext()メソッドが活用されています。while ($iterator->valid()) というループの中で、現在のファイルやディレクトリの情報を取得・表示した後、$iterator->next(); を呼び出すことで、次に処理すべきエントリへと順次進んでいきます。特に、.（現在のディレクトリ）や..（親ディレクトリ）といった特殊なエントリをスキップする際にも、next()メソッドを使って次の有効なエントリへ移動させています。

このようにnext()メソッドは、ディレクトリ内のすべてのエントリを漏れなく、かつ順番に処理するために、反復処理のたびに明示的に呼び出す必要がある、反復子の機能を実現する上で不可欠な要素です。Webサーバーなどのネットワークサービスが、自身のホスト上で特定のディレクトリ内のファイルを管理したり、ユーザーに表示したりするようなシステムで、基本的なディレクトリ走査の操作として利用されます。

Copy
1<?php
2
3/**
4 * 指定されたディレクトリ内のファイルとサブディレクトリのリストをJSON形式で返します。
5 * これは、Next.jsなどのフロントエンドアプリケーションからファイル情報を取得する
6 * シンプルなAPIエンドポイントとして機能することを想定しています。
7 *
8 * @param string $directoryPath リストするディレクトリのパス。
9 * @return void JSON形式のファイルリストを直接出力します。
10 */
11function getDirectoryContentsAsJson(string $directoryPath): void
12{
13    // ディレクトリが存在し、読み込み可能かチェック
14    if (!is_dir($directoryPath) || !is_readable($directoryPath)) {
15        http_response_code(404); // HTTPステータスコード: Not Found
16        header('Content-Type: application/json');
17        echo json_encode(['error' => '指定されたディレクトリが見つからないか、読み込みできません。']);
18        return;
19    }
20
21    $files = [];
22    try {
23        // DirectoryIterator オブジェクトを作成
24        $iterator = new DirectoryIterator($directoryPath);
25
26        // イテレータが有効な間（まだ要素がある間）、ループを続ける
27        while ($iterator->valid()) {
28            // "." (カレントディレクトリ) と ".." (親ディレクトリ) はスキップ
29            if (!$iterator->isDot()) {
30                $files[] = [
31                    'name' => $iterator->getFilename(),  // ファイル名またはディレクトリ名を取得
32                    'type' => $iterator->getType(),      // 'file', 'dir', 'link' のいずれか
33                    // ファイルの場合のみサイズを取得、そうでなければnull
34                    'size' => $iterator->isFile() ? $iterator->getSize() : null,
35                    'lastModified' => $iterator->getMTime(), // 最終更新時刻のUNIXタイムスタンプ
36                ];
37            }
38            // 次のディレクトリ要素に進む
39            // これが DirectoryIterator::next() メソッドの呼び出しです
40            $iterator->next();
41        }
42    } catch (UnexpectedValueException $e) {
43        // ディレクトリが見つからない、またはアクセス権がない場合などの例外処理
44        http_response_code(500); // HTTPステータスコード: Internal Server Error
45        header('Content-Type: application/json');
46        echo json_encode(['error' => 'サーバーエラーが発生しました: ' . $e->getMessage()]);
47        return;
48    }
49
50    // Next.jsなどの別のオリジンからのアクセスを許可するためのCORSヘッダー
51    // 開発環境では'*'が便利ですが、本番環境では特定のオリジンに限定すべきです。
52    header('Access-Control-Allow-Origin: *');
53    header('Content-Type: application/json'); // JSON形式で応答することを指定
54
55    // 収集したファイルリストをJSON形式で出力
56    echo json_encode($files, JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE);
57}
58
59// --- スクリプト実行部分 ---
60// このスクリプトと同じディレクトリのファイルリストを取得する例。
61// Next.jsアプリケーションと連携する際は、Next.jsのpublicディレクトリなど
62// 共有データが格納されているディレクトリを指定することが一般的です。
63$targetDirectory = __DIR__;
64
65// 関数を実行し、結果をJSONとして出力
66getDirectoryContentsAsJson($targetDirectory);
67
68?>

PHPのDirectoryIteratorクラスは、指定したディレクトリ内のファイルやサブディレクトリを一つずつ順番に処理するための機能を提供します。このDirectoryIterator::next()メソッドは、そのイテレータの内部的なポインタを次のファイルやディレクトリへ移動させる役割を持ちます。

具体的には、ディレクトリ内の要素を繰り返し処理する際に、現在の要素の処理が終わった後、次の要素に移るためにこのメソッドを呼び出します。引数はなく、戻り値もありませんが、呼び出すことでイテレータの内部状態が更新され、次にvalid()やcurrent()などのメソッドを呼び出したときに、異なる要素の情報が取得できるようになります。

サンプルコードでは、while ($iterator->valid()) { ... $iterator->next(); }というループ構造の中で利用されています。valid()メソッドでまだ処理すべき要素があるかを確認し、要素があれば処理を行い、next()メソッドで次の要素へ進む、という流れを繰り返すことで、指定されたディレクトリ内のすべてのファイルやサブディレクトリの情報を効率的に収集しています。これにより、Next.jsのようなフロントエンドアプリケーションから利用できるJSON形式のディレクトリ情報を提供するAPIエンドポイントの機能を実現しています。