【PHP8.x】FilesystemIterator::KEY_MODE_MASK定数の使い方

Copy
1<?php
2
3// 動作確認用のディレクトリとファイルを作成します。
4$testDir = __DIR__ . '/php_key_mode_demo';
5if (!is_dir($testDir)) {
6    mkdir($testDir);
7}
8file_put_contents($testDir . '/report.pdf', 'PDF content');
9file_put_contents($testDir . '/image.png', 'Image data');
10// サブディレクトリや隠しファイルは FilesystemIterator::SKIP_DOTS でスキップされるため、
11// シンプルなファイルのみで構成します。
12
13/**
14 * FilesystemIteratorのキーモードがFilesystemIterator::key()メソッドの
15 * 戻り値にどのように影響するかをデモンストレーションします。
16 *
17 * FilesystemIterator::KEY_MODE_MASK は、FilesystemIteratorのコンストラクタに渡す
18 * フラグの中で、イテレータのキー形式を制御するフラグ群 (例: KEY_AS_PATHNAME, KEY_AS_FILENAME, KEY_AS_BASENAME) を
19 * 識別するためのビットマスク定数です。
20 * この定数自体をFilesystemIteratorのコンストラクタに直接渡すことはありませんが、
21 * それが関連するキーモードフラグが FilesystemIterator::key() メソッドの出力に
22 * どう影響するかを示すことで、その目的を理解するのに役立ちます。
23 *
24 * @param string $directory 走査対象のディレクトリパス。
25 */
26function demonstrateFilesystemIteratorKeyModes(string $directory): void
27{
28    echo "--- FilesystemIterator::key() メソッドのデモンストレーション ---\n";
29    echo "対象ディレクトリ: " . realpath($directory) . "\n\n";
30
31    // 1. FilesystemIterator::KEY_AS_PATHNAME を使用した場合
32    //    key() メソッドは、ファイルのフルパス（ディレクトリパスを含む）を返します。
33    echo "■ FilesystemIterator::KEY_AS_PATHNAME の場合:\n";
34    // FilesystemIterator::SKIP_DOTS は . と .. エントリをスキップするために推奨されます。
35    $iteratorPathname = new FilesystemIterator($directory, FilesystemIterator::KEY_AS_PATHNAME | FilesystemIterator::SKIP_DOTS);
36    foreach ($iteratorPathname as $fileinfo) {
37        echo "  key(): " . $iteratorPathname->key() . "\n";
38    }
39    echo "\n";
40
41    // 2. FilesystemIterator::KEY_AS_FILENAME を使用した場合
42    //    key() メソッドは、ファイル名（拡張子を含む）のみを返します。
43    echo "■ FilesystemIterator::KEY_AS_FILENAME の場合:\n";
44    $iteratorFilename = new FilesystemIterator($directory, FilesystemIterator::KEY_AS_FILENAME | FilesystemIterator::SKIP_DOTS);
45    foreach ($iteratorFilename as $fileinfo) {
46        echo "  key(): " . $iteratorFilename->key() . "\n";
47    }
48    echo "\n";
49
50    // 3. FilesystemIterator::KEY_AS_BASENAME を使用した場合
51    //    key() メソッドは、ファイル名（拡張子を含まないベース名）のみを返します。
52    echo "■ FilesystemIterator::KEY_AS_BASENAME の場合:\n";
53    $iteratorBasename = new FilesystemIterator($directory, FilesystemIterator::KEY_AS_BASENAME | FilesystemIterator::SKIP_DOTS);
54    foreach ($iteratorBasename as $fileinfo) {
55        echo "  key(): " . $iteratorBasename->key() . "\n";
56    }
57    echo "\n";
58
59    // FilesystemIterator::KEY_MODE_MASK 定数自体について (補足情報)
60    // この定数自体は、上記の KEY_AS_PATHNAME などのキーモード関連フラグを
61    // ビット演算でグループ化したり、識別したりするために存在します。
62    // そのため、直接この値を FilesystemIterator のコンストラクタに渡すことで
63    // 動作が変わることはありません。
64    echo "--- FilesystemIterator::KEY_MODE_MASK について (補足) ---\n";
65    echo "FilesystemIterator::KEY_MODE_MASK の値: " . FilesystemIterator::KEY_MODE_MASK . " (10進数)\n";
66    echo "これは、key() メソッドが返す値の形式を制御するフラグ群（例: KEY_AS_PATHNAME）を\n";
67    echo "識別するためのマスク値であり、直接イテレータの挙動を設定するものではありません。\n";
68}
69
70// デモンストレーションを実行します。
71demonstrateFilesystemIteratorKeyModes($testDir);
72
73// 後処理: テスト用に作成したディレクトリとファイルを削除します。
74function cleanupTestDirectory(string $dir): void
75{
76    if (!is_dir($dir)) {
77        return;
78    }
79    // ディレクトリ内のファイルをすべて削除
80    $files = new FilesystemIterator($dir, FilesystemIterator::SKIP_DOTS);
81    foreach ($files as $fileinfo) {
82        unlink($fileinfo->getRealPath());
83    }
84    // 空になったディレクトリを削除
85    rmdir($dir);
86    echo "\n--- クリーンアップ完了 ---\n";
87}
88cleanupTestDirectory($testDir);
89
90?>

FilesystemIterator::KEY_MODE_MASKは、PHPのFilesystemIteratorクラスに定義された定数です。これは、FilesystemIterator::key()メソッドが返す値の形式を制御するフラグ群（例えば、FilesystemIterator::KEY_AS_PATHNAME、KEY_AS_FILENAME、KEY_AS_BASENAMEなど）を識別するためのビットマスク定数です。この定数自体をFilesystemIteratorのコンストラクタに直接渡して、イテレータの動作を設定することはありません。

サンプルコードでは、このKEY_MODE_MASKが関連する各キーモードフラグが、FilesystemIterator::key()メソッドの戻り値にどう影響するかをデモンストレーションしています。具体的には、FilesystemIterator::KEY_AS_PATHNAMEを使用するとkey()メソッドはディレクトリパスを含むファイルのフルパスを返し、FilesystemIterator::KEY_AS_FILENAMEを使用するとkey()メソッドは拡張子を含むファイル名のみを返します。また、FilesystemIterator::KEY_AS_BASENAMEを使用するとkey()メソッドは拡張子を含まないファイル名（ベース名）のみを返します。

このように、KEY_MODE_MASKは、FilesystemIteratorがディレクトリ内のファイルを走査する際に、key()メソッドを通じてどのような情報をキーとして提供するかを理解するための補助的な役割を持つ定数です。

Copy
1<?php
2
3/**
4 * FilesystemIterator::KEY_MODE_MASK の使用例を示します。
5 *
6 * この定数は、FilesystemIterator のキーモード関連のフラグを抽出するための
7 * ビットマスクとして機能します。これにより、設定されたフラグの中から
8 * キーの振る舞いを決定する部分を識別できます。
9 */
10function demonstrateFilesystemIteratorKeyMode(): void
11{
12    // 一時ディレクトリとダミーファイルを作成します。
13    $tempDir = sys_get_temp_dir() . '/filesystem_iterator_example_' . uniqid();
14    if (!mkdir($tempDir) && !is_dir($tempDir)) {
15        throw new \RuntimeException(sprintf('Directory "%s" was not created', $tempDir));
16    }
17    file_put_contents($tempDir . '/item1.txt', 'Content A');
18    file_put_contents($tempDir . '/item2.log', 'Content B');
19
20    echo "--- 一時ディレクトリ作成: {$tempDir} ---\n\n";
21
22    // 1. デフォルトの KEY_AS_PATHNAME モードでのイテレーション
23    // KEY_AS_PATHNAME は FilesystemIterator のデフォルトのキーモードです。
24    echo "--- FilesystemIterator::KEY_AS_PATHNAME (デフォルト) ---\n";
25    $iteratorDefault = new FilesystemIterator($tempDir);
26
27    // イテレータの実際のフラグからキーモード部分を抽出します。
28    // KEY_MODE_MASK を使用して、キーモード関連のビットのみを分離します。
29    $extractedDefaultKeyMode = $iteratorDefault->getFlags() & FilesystemIterator::KEY_MODE_MASK;
30    echo "  実際のイテレータフラグ: " . $iteratorDefault->getFlags() . "\n";
31    echo "  抽出されたキーモード: " . $extractedDefaultKeyMode . " (期待値: " . FilesystemIterator::KEY_AS_PATHNAME . ")\n";
32
33    foreach ($iteratorDefault as $key => $fileInfo) {
34        echo "  キー: '{$key}' (パス名) -> ファイル名: " . $fileInfo->getFilename() . "\n";
35    }
36    echo "\n";
37
38    // 2. KEY_AS_FILENAME モードでのイテレーション
39    // ファイル名がキーとなるように設定し、親ディレクトリ (".") と現在のディレクトリ ("..") をスキップします。
40    $flagsFilename = FilesystemIterator::KEY_AS_FILENAME | FilesystemIterator::SKIP_DOTS;
41    echo "--- FilesystemIterator::KEY_AS_FILENAME ---\n";
42    echo "  設定フラグ: " . $flagsFilename . "\n";
43    $iteratorFilename = new FilesystemIterator($tempDir, $flagsFilename);
44
45    // 設定されたフラグからキーモード部分を抽出します。
46    $extractedFilenameKeyMode = $iteratorFilename->getFlags() & FilesystemIterator::KEY_MODE_MASK;
47    echo "  実際のイテレータフラグ: " . $iteratorFilename->getFlags() . "\n";
48    echo "  抽出されたキーモード: " . $extractedFilenameKeyMode . " (期待値: " . FilesystemIterator::KEY_AS_FILENAME . ")\n";
49
50    foreach ($iteratorFilename as $key => $fileInfo) {
51        echo "  キー: '{$key}' (ファイル名) -> パス名: " . $fileInfo->getPathname() . "\n";
52    }
53    echo "\n";
54
55    // 3. KEY_AS_ARRAY_KEY モードでのイテレーション
56    // 0からの連番がキーとなるように設定し、ドットファイルをスキップします。
57    $flagsArrayKey = FilesystemIterator::KEY_AS_ARRAY_KEY | FilesystemIterator::SKIP_DOTS;
58    echo "--- FilesystemIterator::KEY_AS_ARRAY_KEY ---\n";
59    echo "  設定フラグ: " . $flagsArrayKey . "\n";
60    $iteratorArrayKey = new FilesystemIterator($tempDir, $flagsArrayKey);
61
62    // 設定されたフラグからキーモード部分を抽出します。
63    $extractedArrayKeyMode = $iteratorArrayKey->getFlags() & FilesystemIterator::KEY_MODE_MASK;
64    echo "  実際のイテレータフラグ: " . $iteratorArrayKey->getFlags() . "\n";
65    echo "  抽出されたキーモード: " . $extractedArrayKeyMode . " (期待値: " . FilesystemIterator::KEY_AS_ARRAY_KEY . ")\n";
66
67    foreach ($iteratorArrayKey as $key => $fileInfo) {
68        echo "  キー: '{$key}' (配列キー) -> ファイル名: " . $fileInfo->getFilename() . "\n";
69    }
70    echo "\n";
71
72    // KEY_MODE_MASK 定数とその関連定数の値を確認
73    echo "--- KEY_MODE_MASK と関連定数の値 ---\n";
74    echo "  FilesystemIterator::KEY_AS_PATHNAME: " . FilesystemIterator::KEY_AS_PATHNAME . "\n";
75    echo "  FilesystemIterator::KEY_AS_FILENAME: " . FilesystemIterator::KEY_AS_FILENAME . "\n";
76    echo "  FilesystemIterator::KEY_AS_ARRAY_KEY: " . FilesystemIterator::KEY_AS_ARRAY_KEY . "\n";
77    echo "  FilesystemIterator::KEY_MODE_MASK: " . FilesystemIterator::KEY_MODE_MASK . "\n";
78    echo "  KEY_MODE_MASK は、これらのキーモード定数のどれか一つを表すビットを分離するために使用されます。\n\n";
79
80    // 後処理: 一時ディレクトリとその中のファイルを削除します。
81    array_map('unlink', glob("{$tempDir}/*"));
82    rmdir($tempDir);
83    echo "--- 一時ディレクトリ削除: {$tempDir} ---\n";
84}
85
86// 関数を実行します。
87demonstrateFilesystemIteratorKeyMode();

PHPのFilesystemIterator::KEY_MODE_MASKは、FilesystemIteratorクラスに定義された定数です。この定数は、ディレクトリ内のファイルやディレクトリを繰り返し処理（イテレーション）する際に、各項目が持つ「キー」の振る舞いを決定する設定（キーモードフラグ）を、他の多くの設定フラグの中から識別・抽出するための「ビットマスク」として機能します。

FilesystemIteratorは、イテレーションのキーとしてファイルの完全なパス名（KEY_AS_PATHNAME）、ファイル名のみ（KEY_AS_FILENAME）、または0からの連番（KEY_AS_ARRAY_KEY）など、複数のモードを持つことができます。KEY_MODE_MASKを使用すると、FilesystemIteratorに設定された全てのフラグの中から、現在どのキーモードが有効になっているかをプログラム的に確認できます。具体的には、$iterator->getFlags() & FilesystemIterator::KEY_MODE_MASKのようにビットAND演算を用いることで、キーモードに関する情報のみを分離して取得できます。

このKEY_MODE_MASKは定数であるため、引数を取ることはなく、特定の処理結果を返す戻り値もありません。それは、あくまで他のフラグから特定の情報を取り出すための数値的なパターン（マスク）として利用されます。