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

Copy
1<?php
2
3/**
4 * RecursiveDirectoryIterator の FOLLOW_SYMLINKS 定数の使用例
5 *
6 * この関数は、一時的なディレクトリ構造とシンボリックリンクを作成し、
7 * RecursiveDirectoryIterator::FOLLOW_SYMLINKS フラグの有無による
8 * ディレクトリの走査挙動の違いを示します。
9 *
10 * RecursiveDirectoryIterator::FOLLOW_SYMLINKS 定数は、
11 * RecursiveDirectoryIterator がシンボリックリンクを見つけたときに、
12 * そのリンクが指す先のファイルやディレクトリを追跡して、
13 * 走査の対象に含めるかどうかを制御するためのフラグです。
14 * 値は整数です。
15 */
16function demonstrateRecursiveDirectoryIteratorSymlinks(): void
17{
18    // 一時ディレクトリのパスを定義
19    // このディレクトリはスクリプト実行中に作成され、終了時に削除されます。
20    $tempDir = sys_get_temp_dir() . DIRECTORY_SEPARATOR . 'php_symlink_test_' . uniqid();
21    $realSubDir = $tempDir . DIRECTORY_SEPARATOR . 'real_subdir';
22    $symlinkSubDir = $tempDir . DIRECTORY_SEPARATOR . 'symlink_to_subdir';
23    $realFile = $realSubDir . DIRECTORY_SEPARATOR . 'real_file.txt';
24
25    // ディレクトリとファイルを作成
26    // mkdir(パス, 権限, 再帰的に作成するか)
27    mkdir($realSubDir, 0777, true);
28    // file_put_contents(ファイル名, 内容)
29    file_put_contents($realFile, 'Content of real_file.txt');
30
31    // シンボリックリンクを作成
32    // symlink(リンク元のパス, リンク先のパス)
33    // Windows環境では、この関数を実行するために管理者権限が必要な場合や、
34    // 開発者モードが有効になっている必要があります。
35    // そのため、シンボリックリンクの作成に失敗する可能性があります。
36    $symlinkCreated = false;
37    if (file_exists($realSubDir)) {
38        if (symlink($realSubDir, $symlinkSubDir)) {
39            $symlinkCreated = true;
40            echo "一時的なディレクトリ構造とシンボリックリンクを作成しました。\n";
41            echo " - ベースディレクトリ: {$tempDir}\n";
42            echo " - 実際のサブディレクトリ (リンク元): {$realSubDir}\n";
43            echo " - シンボリックリンク (指向先: {$realSubDir}): {$symlinkSubDir}\n\n";
44        } else {
45            echo "シンボリックリンクの作成に失敗しました。\n";
46            echo "権限不足などの理由で symlink() が機能しない場合があります。\n";
47            echo "このため、シンボリックリンクの追跡挙動は一部実演できません。\n\n";
48        }
49    } else {
50        echo "実際のサブディレクトリが存在しないため、シンボリックリンクは作成されませんでした。\n\n";
51    }
52
53    // --- シンボリックリンクを追跡しない場合 (RecursiveDirectoryIterator::FOLLOW_SYMLINKS なし) ---
54    echo "--- シンボリックリンクを追跡しない場合 (FOLLOW_SYMLINKS フラグなし) ---\n";
55    echo "  (シンボリックリンクは単一のファイルシステムエントリとして扱われ、その中身は走査されません)\n";
56    try {
57        // RecursiveDirectoryIterator のコンストラクタには、ディレクトリパスとフラグを渡す
58        // ここでは RecursiveDirectoryIterator::FOLLOW_SYMLINKS フラグを含めない
59        $iterator = new RecursiveDirectoryIterator(
60            $tempDir,
61            RecursiveDirectoryIterator::SKIP_DOTS // ドットエントリ (. と ..) をスキップするフラグ
62        );
63        // RecursiveIteratorIterator を使って、ディレクトリを再帰的に走査
64        $recursiveIterator = new RecursiveIteratorIterator($iterator);
65
66        foreach ($recursiveIterator as $fileInfo) {
67            echo "  パス: " . $fileInfo->getPathname();
68            if ($fileInfo->isLink()) {
69                echo " (シンボリックリンク)";
70            } elseif ($fileInfo->isDir()) {
71                echo " (ディレクトリ)";
72            } else {
73                echo " (ファイル)";
74            }
75            echo "\n";
76        }
77    } catch (UnexpectedValueException $e) {
78        // 指定されたディレクトリが存在しない場合などに発生
79        echo "  エラー: " . $e->getMessage() . "\n";
80    }
81
82    echo "\n--- RecursiveDirectoryIterator::FOLLOW_SYMLINKS を使用してシンボリックリンクを追跡する場合 ---\n";
83    if ($symlinkCreated) {
84        echo "  (RecursiveDirectoryIterator::FOLLOW_SYMLINKS フラグを使用すると、\n";
85        echo "   シンボリックリンクの指す先も再帰的に走査の対象となります。リンク自体は表示されません)\n";
86        try {
87            // RecursiveDirectoryIterator::FOLLOW_SYMLINKS フラグを含めることで、
88            // シンボリックリンクの指す先も再帰的に走査の対象となる
89            $iterator = new RecursiveDirectoryIterator(
90                $tempDir,
91                RecursiveDirectoryIterator::SKIP_DOTS | RecursiveDirectoryIterator::FOLLOW_SYMLINKS
92            );
93            $recursiveIterator = new RecursiveIteratorIterator($iterator);
94
95            foreach ($recursiveIterator as $fileInfo) {
96                echo "  パス: " . $fileInfo->getPathname();
97                // FOLLOW_SYMLINKS を指定した場合、イテレータはリンクの指す先を辿るため、
98                // 通常は isLink() は false を返します（リンク自体ではなく、その中身を見ているため）。
99                if ($fileInfo->isLink()) {
100                    echo " (シンボリックリンク)";
101                } elseif ($fileInfo->isDir()) {
102                    echo " (ディレクトリ)";
103                } else {
104                    echo " (ファイル)";
105                }
106                echo "\n";
107            }
108        } catch (UnexpectedValueException $e) {
109            echo "  エラー: " . $e->getMessage() . "\n";
110        }
111    } else {
112        echo "  シンボリックリンクが作成できなかったため、追跡挙動のデモンストレーションはスキップされます。\n";
113    }
114
115    // --- 後処理: 作成したディレクトリとファイルを削除 ---
116    echo "\n一時ディレクトリをクリーンアップ中...\n";
117    try {
118        if (is_dir($tempDir)) {
119            // RecursiveDirectoryIterator を使って、一時ディレクトリ内のすべてのファイルとサブディレクトリを削除
120            // RecursiveIteratorIterator::CHILD_FIRST は、子要素から先に処理することを意味し、
121            // ディレクトリを安全に削除するために必要です。
122            $files = new RecursiveIteratorIterator(
123                new RecursiveDirectoryIterator($tempDir, RecursiveDirectoryIterator::SKIP_DOTS),
124                RecursiveIteratorIterator::CHILD_FIRST
125            );
126
127            foreach ($files as $fileinfo) {
128                if ($fileinfo->isDir()) {
129                    rmdir($fileinfo->getRealPath()); // ディレクトリを削除
130                } else {
131                    unlink($fileinfo->getRealPath()); // ファイルを削除
132                }
133            }
134            rmdir($tempDir); // 最上位の一時ディレクトリを削除
135            echo "クリーンアップが完了しました。\n";
136        } else {
137            echo "クリーンアップするディレクトリが見つかりませんでした。\n";
138        }
139    } catch (Throwable $e) {
140        // クリーンアップ中にエラーが発生した場合
141        echo "クリーンアップ中にエラーが発生しました: " . $e->getMessage() . "\n";
142        echo "手動で '{$tempDir}' を削除する必要があるかもしれません。\n";
143    }
144}
145
146// 関数を実行
147demonstrateRecursiveDirectoryIteratorSymlinks();

RecursiveDirectoryIterator::FOLLOW_SYMLINKSは、PHPのRecursiveDirectoryIteratorクラスに属する定数です。この定数は整数値であり、ディレクトリを再帰的に走査する際に、シンボリックリンク（別のファイルやディレクトリへの参照）をどのように扱うかを制御するフラグとして機能します。

サンプルコードは、一時的なディレクトリ構造とシンボリックリンクを作成し、このFOLLOW_SYMLINKS定数の有無がRecursiveDirectoryIteratorの走査挙動にどう影響するかを示しています。

この定数を指定しない場合、RecursiveDirectoryIteratorはシンボリックリンク自体を単一のファイルシステムエントリとして認識し、そのリンクが指し示す先のコンテンツは走査の対象に含まれません。つまり、リンクはファイルやディレクトリの一種としてリストアップされますが、その内部には踏み込みません。

一方、RecursiveDirectoryIterator::FOLLOW_SYMLINKSを指定すると、イテレータはシンボリックリンクが指し示す先の実際のファイルやディレクトリへと移動し、その中身も再帰的な走査の対象に含めます。これにより、リンク先のコンテンツが物理的にその場にあるかのように扱われます。

この定数をRecursiveDirectoryIteratorのコンストラクタにフラグとして渡すことで、シンボリックリンクを追跡して内容を含めるか、または追跡せずにリンク自体を単なるエントリとして扱うかを制御できます。

Copy
1<?php
2
3/**
4 * RecursiveDirectoryIterator::FOLLOW_SYMLINKS 定数を使用して、
5 * シンボリックリンクを辿りながらディレクトリを再帰的に走査するPHPのサンプルコードです。
6 *
7 * システムエンジニアを目指す初心者の方にも理解しやすいよう、
8 * 一時的なディレクトリ構造の作成から、シンボリックリンクの挙動、
9 * そしてリソースのクリーンアップまでを一つの関数にまとめています。
10 *
11 * キーワード: php fpm follow symlinks
12 * PHP-FPMのようなWebサーバー環境で、シンボリックリンクを含むファイルシステムの走査が必要な場合に役立ちます。
13 */
14function demonstrateRecursiveDirectoryIterationWithSymlinks(): void
15{
16    // 1. 一時的なテストディレクトリとファイルを準備します。
17    // uniqid() を使って一意なディレクトリ名を作成し、他のテストと干渉しないようにします。
18    $baseDir = sys_get_temp_dir() . DIRECTORY_SEPARATOR . 'php_symlink_test_' . uniqid();
19
20    // ベースディレクトリの作成とエラーチェック
21    if (!mkdir($baseDir) && !is_dir($baseDir)) {
22        echo "エラー: ベースディレクトリ '" . $baseDir . "' の作成に失敗しました。\n";
23        return;
24    }
25
26    // 実際のデータが格納されるディレクトリを作成します。
27    $realDirPath = $baseDir . DIRECTORY_SEPARATOR . 'real_data';
28    if (!mkdir($realDirPath) && !is_dir($realDirPath)) {
29        echo "エラー: 実データディレクトリ '" . $realDirPath . "' の作成に失敗しました。\n";
30        // 失敗した場合は、作成済みのベースディレクトリを削除して終了します。
31        rmdir($baseDir);
32        return;
33    }
34    // 実ディレクトリ内にファイルとサブディレクトリを作成します。
35    file_put_contents($realDirPath . DIRECTORY_SEPARATOR . 'file_in_real.txt', 'これは実ディレクトリ内のファイルです。');
36    mkdir($realDirPath . DIRECTORY_SEPARATOR . 'sub_dir');
37    file_put_contents($realDirPath . DIRECTORY_SEPARATOR . 'sub_dir' . DIRECTORY_SEPARATOR . 'sub_file.txt', 'これはサブディレクトリ内のファイルです。');
38
39    // 2. 実際のディレクトリへのシンボリックリンクを作成します。
40    $symlinkPath = $baseDir . DIRECTORY_SEPARATOR . 'linked_data';
41    // symlink() の第一引数はターゲット（実体）、第二引数はリンク名です。
42    // Windowsでは管理者権限が必要な場合があります。
43    if (!symlink($realDirPath, $symlinkPath)) {
44        echo "エラー: シンボリックリンク '" . $symlinkPath . "' の作成に失敗しました。\n";
45        echo "Windows環境では管理者権限が必要な場合があります。または、ファイルシステムの種類を確認してください。\n";
46        // シンボリックリンク作成に失敗した場合、ここまでに作成したリソースをクリーンアップします。
47        unlink($realDirPath . DIRECTORY_SEPARATOR . 'sub_dir' . DIRECTORY_SEPARATOR . 'sub_file.txt');
48        rmdir($realDirPath . DIRECTORY_SEPARATOR . 'sub_dir');
49        unlink($realDirPath . DIRECTORY_SEPARATOR . 'file_in_real.txt');
50        rmdir($realDirPath);
51        rmdir($baseDir);
52        return;
53    }
54
55    echo "--- ディレクトリ構造のセットアップ完了 ---\n";
56    echo "ベースディレクトリ: " . $baseDir . "\n";
57    echo "実データディレクトリ (本体): " . $realDirPath . "\n";
58    echo "シンボリックリンク (実データディレクトリを指す): " . $symlinkPath . "\n\n";
59
60    echo "--- シンボリックリンクを辿ってディレクトリを走査 (RecursiveDirectoryIterator::FOLLOW_SYMLINKS 使用) ---\n";
61    echo "RecursiveDirectoryIterator::FOLLOW_SYMLINKS フラグが指定されているため、\n";
62    echo "シンボリックリンクの先のファイルも通常のファイルとしてリストアップされます。\n\n";
63
64    try {
65        // RecursiveDirectoryIterator を使用してディレクトリを走査します。
66        // RecursiveDirectoryIterator::FOLLOW_SYMLINKS: シンボリックリンクが指すディレクトリの中身を再帰的に走査します。
67        // RecursiveDirectoryIterator::SKIP_DOTS: '.' と '..' ディレクトリ（現在のディレクトリと親ディレクトリ）をスキップします。
68        $iterator = new RecursiveDirectoryIterator(
69            $baseDir,
70            RecursiveDirectoryIterator::SKIP_DOTS | RecursiveDirectoryIterator::FOLLOW_SYMLINKS
71        );
72
73        // RecursiveIteratorIterator は、再帰的なイテレータをフラットなリストとして扱えるようにします。
74        $recursiveIterator = new RecursiveIteratorIterator($iterator);
75
76        // ディレクトリ内のすべてのファイルとディレクトリを走査し、パスを表示します。
77        foreach ($recursiveIterator as $fileInfo) {
78            // SplFileInfo オブジェクトからファイルやディレクトリのパスを取得します。
79            echo "発見: " . $fileInfo->getPathname() . "\n";
80        }
81    } catch (UnexpectedValueException $e) {
82        // 例外が発生した場合（例: ベースディレクトリが存在しないなど）
83        echo "エラー: ディレクトリ走査中に問題が発生しました - " . $e->getMessage() . "\n";
84    } finally {
85        echo "\n--- クリーンアップ中 ---\n";
86        // 3. 作成した一時ディレクトリとファイルを削除してクリーンアップします。
87        // RecursiveDirectoryIterator と RecursiveIteratorIterator::CHILD_FIRST を使用すると、
88        // 子要素（ファイル）から先に処理されるため、ディレクトリの削除が容易になります。
89        $files = new RecursiveIteratorIterator(
90            new RecursiveDirectoryIterator($baseDir, RecursiveDirectoryIterator::SKIP_DOTS),
91            RecursiveIteratorIterator::CHILD_FIRST
92        );
93
94        foreach ($files as $file) {
95            if ($file->isLink()) {
96                // シンボリックリンク自体を削除します (リンク先は削除しません)。
97                unlink($file->getPathname());
98            } elseif ($file->isDir()) {
99                // 空になったディレクトリを削除します。
100                rmdir($file->getRealPath());
101            } else {
102                // ファイルを削除します。
103                unlink($file->getRealPath());
104            }
105        }
106        // 最後に、作成したベースディレクトリを削除します。
107        rmdir($baseDir);
108        echo "クリーンアップ完了。\n";
109    }
110}
111
112// 関数を実行してデモンストレーションを開始します。
113demonstrateRecursiveDirectoryIterationWithSymlinks();
114

このPHPコードは、RecursiveDirectoryIterator::FOLLOW_SYMLINKS定数を利用して、シンボリックリンクの先にあるディレクトリやファイルを再帰的に走査する方法を示しています。まず、テスト用に一時的なディレクトリと、実データを指すシンボリックリンクを作成します。次に、RecursiveDirectoryIteratorをFOLLOW_SYMLINKSとSKIP_DOTS（.と..を無視する）のフラグを組み合わせてインスタンス化し、RecursiveIteratorIteratorで内部のすべての要素を一つずつ辿ります。RecursiveDirectoryIterator::FOLLOW_SYMLINKS定数（これは内部的に整数値を持ちます）を指定することで、イテレータはシンボリックリンク自体ではなく、そのリンクが指し示す実際のディレクトリの内容を追跡し、再帰的に走査します。これにより、例えばPHP-FPMのような環境で、シンボリックリンクを通じて外部のストレージや共通リソースにアクセスする場合でも、その内容を効果的に処理できます。処理後は、作成した一時リソースが適切に削除され、クリーンアップが完了します。