【PHP8.x】RecursiveDirectoryIterator::KEY_AS_PATHNAME定数の使い方

Copy
1<?php
2
3/**
4 * RecursiveDirectoryIterator::KEY_AS_PATHNAME 定数を使用して、
5 * ディレクトリのイテレーション時にキーとしてパス名を取得するサンプルです。
6 *
7 * この関数は、指定されたディレクトリの内容を再帰的に走査し、
8 * 各ファイルやディレクトリのフルパス名をイテレータのキーとして出力します。
9 *
10 * @param string $directoryPath 走査するディレクトリのパス
11 * @return void
12 */
13function iterateDirectoryWithFullPathKeys(string $directoryPath): void
14{
15    // 指定されたパスがディレクトリとして存在しない場合はエラーメッセージを表示し、処理を終了します。
16    if (!is_dir($directoryPath)) {
17        echo "エラー: 指定されたディレクトリ '{$directoryPath}' が見つかりません。\n";
18        return;
19    }
20
21    try {
22        // RecursiveDirectoryIterator を初期化します。
23        // RecursiveDirectoryIterator::SKIP_DOTS は、特殊なエントリ "." と ".." をスキップするために使用します。
24        // RecursiveDirectoryIterator::KEY_AS_PATHNAME は、イテレータのキーとして
25        // ファイルやディレクトリのフルパス名を使用するよう設定する定数です。
26        $directoryIterator = new RecursiveDirectoryIterator(
27            $directoryPath,
28            RecursiveDirectoryIterator::SKIP_DOTS | RecursiveDirectoryIterator::KEY_AS_PATHNAME
29        );
30
31        // RecursiveIteratorIterator は、RecursiveDirectoryIterator と組み合わせて
32        // ディレクトリツリーを再帰的に（サブディレクトリの中も）走査するために使用します。
33        $iterator = new RecursiveIteratorIterator($directoryIterator);
34
35        echo "ディレクトリ '{$directoryPath}' の内容を走査中 (キーはパス名):\n";
36        echo "----------------------------------------\n";
37
38        // ディレクトリ内の各要素（ファイルやサブディレクトリ）をイテレートします。
39        foreach ($iterator as $key => $fileInfo) {
40            // ここで、$key は RecursiveDirectoryIterator::KEY_AS_PATHNAME 定数の設定により、
41            // ファイルまたはディレクトリのフルパス名になります。
42            // $fileInfo は SplFileInfo オブジェクトで、ファイルに関する詳細情報（名前、パス、タイプなど）を提供します。
43            echo "キー (パス名): '{$key}'\n";
44            echo "  ファイル名: '{$fileInfo->getFilename()}'\n";
45            echo "  タイプ: " . ($fileInfo->isDir() ? 'ディレクトリ' : 'ファイル') . "\n";
46            echo "----------------------------------------\n";
47        }
48    } catch (UnexpectedValueException $e) {
49        // ディレクトリへのアクセス権がないなど、予期せぬ問題が発生した場合にエラーを捕捉します。
50        echo "エラー: ディレクトリの処理中に問題が発生しました: " . $e->getMessage() . "\n";
51    }
52}
53
54// サンプルとして、このスクリプトが実行されている現在のディレクトリを対象とします。
55// このディレクトリ内のファイルやサブディレクトリが再帰的に走査され、
56// それぞれのフルパス名がキーとして表示されます。
57$targetDirectory = __DIR__;
58
59// 作成した関数を呼び出して実行します。
60iterateDirectoryWithFullPathKeys($targetDirectory);

PHP 8のRecursiveDirectoryIterator::KEY_AS_PATHNAME定数は、ディレクトリを再帰的に走査する際に、イテレータのキーとしてファイルやディレクトリのフルパス名を取得するために使用される定数です。この定数は整数値を持ち、RecursiveDirectoryIteratorのコンストラクタに他のオプションと組み合わせて渡すことで、イテレーション時のキーの動作を設定します。

サンプルコードのiterateDirectoryWithFullPathKeys関数は、引数として$directoryPath（走査したいディレクトリのパス）を受け取り、そのディレクトリ内のすべてのファイルやサブディレクトリを再帰的に探索します。この関数は特に値を返さないため、戻り値はvoidです。RecursiveDirectoryIteratorを初期化する際にKEY_AS_PATHNAME定数を指定することで、foreachループでディレクトリ内の要素を順に処理する際、$key変数に各ファイルやディレクトリのフルパス名（例: /path/to/directory/file.txt）が格納されるようになります。これにより、ファイルやディレクトリの場所をキーとして直接参照でき、ファイルシステムの構造を効率的に把握したり、特定のパスに基づいて処理を行ったりする際に非常に便利です。

Copy
1<?php
2
3/**
4 * RecursiveDirectoryIterator::KEY_AS_PATHNAME の使用例
5 *
6 * この定数を使用すると、RecursiveDirectoryIterator が返す各要素のキーが
7 * ファイル名ではなく、イテレータの基点からの相対パス名になります。
8 *
9 * システムエンジニアを目指す初心者の方にも分かりやすいように、
10 * キーがどのように変化するかを示します。
11 */
12function demonstrateKeyAsPathname(): void
13{
14    echo "RecursiveDirectoryIterator::KEY_AS_PATHNAME の使用例:\n";
15    echo "この定数を使用すると、イテレータのキーがファイル名ではなく、パス名になります。\n\n";
16
17    // --- テスト用のダミーディレクトリ構造の作成 ---
18    // 実行環境に影響を与えないよう、システムの一時ディレクトリ内に作成します。
19    $baseDir = sys_get_temp_dir() . DIRECTORY_SEPARATOR . 'php_key_example_' . uniqid();
20    if (!mkdir($baseDir) && !is_dir($baseDir)) {
21        throw new \RuntimeException(sprintf('Directory "%s" was not created', $baseDir));
22    }
23    mkdir($baseDir . DIRECTORY_SEPARATOR . 'subdir_a');
24    file_put_contents($baseDir . DIRECTORY_SEPARATOR . 'file1.txt', 'Content of file1.');
25    file_put_contents($baseDir . DIRECTORY_SEPARATOR . 'subdir_a' . DIRECTORY_SEPARATOR . 'file_a1.txt', 'Content of file_a1.');
26    // --------------------------------------------
27
28    try {
29        echo "--- RecursiveDirectoryIterator::KEY_AS_PATHNAME を使用した場合 --- \n";
30        echo "キーは 'base_directory/sub_directory/file_name' の形式になります。\n\n";
31
32        // RecursiveDirectoryIterator を KEY_AS_PATHNAME フラグを付けて作成します。
33        // SKIP_DOTS は . (カレントディレクトリ) と .. (親ディレクトリ) を無視するフラグです。
34        // KEY_AS_PATHNAME が指定されているため、イテレータのキーはファイル名ではなくパス名になります。
35        $directoryIterator = new RecursiveDirectoryIterator(
36            $baseDir,
37            RecursiveDirectoryIterator::SKIP_DOTS | RecursiveDirectoryIterator::KEY_AS_PATHNAME
38        );
39
40        // RecursiveIteratorIterator を使用して、サブディレクトリを再帰的に走査します。
41        // LEAVES_ONLY はファイルのみを返し、ディレクトリ自体は返さないようにします。
42        $iterator = new RecursiveIteratorIterator($directoryIterator, RecursiveIteratorIterator::LEAVES_ONLY);
43
44        foreach ($iterator as $key => $fileInfo) {
45            // $key は RecursiveDirectoryIterator::KEY_AS_PATHNAME フラグによって、
46            // $baseDir からの相対パス（例: file1.txt, subdir_a/file_a1.txt）となります。
47            // $fileInfo は SplFileInfo オブジェクトで、ファイルに関する詳細情報を提供します。
48            echo "キー (KEY_AS_PATHNAME): " . $key . "\n";
49            echo "  ファイル名 (getFilename()): " . $fileInfo->getFilename() . "\n";
50            echo "  フルパス (getRealPath()): " . $fileInfo->getRealPath() . "\n";
51            echo "--------------------------------------------------------\n";
52        }
53
54        echo "\n--- 比較のため、デフォルト動作 (KEY_AS_FILENAME) の場合 --- \n";
55        echo "キーは 'file_name' の形式になります。\n\n";
56
57        // 比較のために、KEY_AS_FILENAME (デフォルト動作、または明示的に指定) の場合を示します。
58        // この場合、イテレータのキーはファイル名（ベース名）になります。
59        $directoryIteratorDefault = new RecursiveDirectoryIterator(
60            $baseDir,
61            RecursiveDirectoryIterator::SKIP_DOTS | RecursiveDirectoryIterator::KEY_AS_FILENAME
62        );
63        $iteratorDefault = new RecursiveIteratorIterator($directoryIteratorDefault, RecursiveIteratorIterator::LEAVES_ONLY);
64
65        foreach ($iteratorDefault as $key => $fileInfo) {
66            // $key は RecursiveDirectoryIterator::KEY_AS_FILENAME フラグによって、
67            // ファイル名（例: file1.txt, file_a1.txt）となります。
68            echo "キー (KEY_AS_FILENAME): " . $key . "\n";
69            echo "  ファイル名 (getFilename()): " . $fileInfo->getFilename() . "\n";
70            echo "  フルパス (getRealPath()): " . $fileInfo->getRealPath() . "\n";
71            echo "--------------------------------------------------------\n";
72        }
73
74    } finally {
75        // --- ダミーディレクトリ構造のクリーンアップ ---
76        // 作成したファイルとディレクトリを削除し、環境を元に戻します。
77        $filesToDelete = new RecursiveIteratorIterator(
78            new RecursiveDirectoryIterator($baseDir, RecursiveDirectoryIterator::SKIP_DOTS),
79            RecursiveIteratorIterator::CHILD_FIRST
80        );
81        foreach ($filesToDelete as $fileinfo) {
82            if ($fileinfo->isDir()) {
83                rmdir($fileinfo->getRealPath());
84            } else {
85                unlink($fileinfo->getRealPath());
86            }
87        }
88        rmdir($baseDir);
89        // --------------------------------------------
90    }
91}
92
93// 関数を実行し、RecursiveDirectoryIterator::KEY_AS_PATHNAME の動作を確認します。
94demonstrateKeyAsPathname();

RecursiveDirectoryIterator::KEY_AS_PATHNAMEは、PHP 8で導入されたRecursiveDirectoryIteratorクラスに属する定数です。この定数は、ディレクトリを再帰的に走査する際に、イテレータが返す各要素の「キー」の形式を決定するために利用されます。

通常、RecursiveDirectoryIteratorが返す要素のキーはファイル名（KEY_AS_FILENAMEがデフォルト、または明示的に指定した場合）となりますが、KEY_AS_PATHNAME定数を指定してイテレータを初期化すると、キーがファイル名ではなく、イテレータの基点となるディレクトリからの相対パス名に変わります。例えば、base_dir/sub_dir/file.txtというパスのファイルに対し、キーがfile.txtではなくsub_dir/file.txtのようになります。

これにより、ディレクトリ構造内で同じファイル名を持つ複数のファイルを、パス情報を含んだキーで一意に識別し、処理することが可能になります。この定数自体は引数を取らず、戻り値として整数値（int）を持ち、RecursiveDirectoryIteratorのコンストラクタのフラグ引数として他のオプションと組み合わせて指定して使用します。ファイルパス全体をキーとして利用したい場合に大変便利です。