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

Copy
1<?php
2
3// このファイルを実行する前に、PHPのPhar拡張が有効になっていることを確認してください。
4// php.iniファイルで 'phar.readonly = 0' を設定する必要がある場合があります。
5// (例: php -d phar.readonly=0 your_script.php)
6
7/**
8 * テスト用のファイルとディレクトリを作成します。
9 * アーカイブに含める元データとして使用します。
10 *
11 * @param string $baseDir ベースディレクトリのパス
12 * @return void
13 */
14function setupTestFiles(string $baseDir): void
15{
16    // ベースディレクトリが存在しない場合は作成します
17    if (!is_dir($baseDir)) {
18        mkdir($baseDir, 0777, true); // 0777は読み書き実行権限、trueは再帰的に作成を許可
19    }
20
21    // テスト用のファイルをいくつか作成します
22    file_put_contents($baseDir . '/file1.txt', 'これはファイル1のコンテンツです。');
23    file_put_contents($baseDir . '/file2.log', 'ログエントリ1\nログエントリ2');
24
25    // サブディレクトリとそこに含まれるファイルを作成します
26    mkdir($baseDir . '/subfolder', 0777);
27    file_put_contents($baseDir . '/subfolder/nested_file.html', '<h1>ネストされたファイル</h1>');
28
29    echo "テスト用のファイルとディレクトリを作成しました: " . realpath($baseDir) . "\n";
30}
31
32/**
33 * テストで作成したファイル、ディレクトリ、およびアーカイブをクリーンアップします。
34 *
35 * @param string $baseDir ベースディレクトリのパス
36 * @param string $archiveFile 作成されたアーカイブファイルのパス
37 * @return void
38 */
39function cleanupTestFiles(string $baseDir, string $archiveFile): void
40{
41    // 作成されたアーカイブファイルがあれば削除します
42    if (file_exists($archiveFile)) {
43        unlink($archiveFile);
44    }
45
46    // ベースディレクトリとその内容を再帰的に削除します
47    if (is_dir($baseDir)) {
48        // RecursiveIteratorIterator と RecursiveDirectoryIterator を使用して、
49        // ディレクトリ内のすべてのファイルとサブディレクトリを効率的に走査します。
50        // CHILD_FIRST はサブディレクトリ内のファイルを先に削除するために重要です。
51        $files = new RecursiveIteratorIterator(
52            new RecursiveDirectoryIterator($baseDir, RecursiveDirectoryIterator::SKIP_DOTS),
53            RecursiveIteratorIterator::CHILD_FIRST
54        );
55
56        foreach ($files as $fileinfo) {
57            // ファイルかディレクトリかによって削除方法を変えます
58            if ($fileinfo->isDir()) {
59                rmdir($fileinfo->getRealPath()); // ディレクトリを削除
60            } else {
61                unlink($fileinfo->getRealPath()); // ファイルを削除
62            }
63        }
64        rmdir($baseDir); // 空になったベースディレクトリを削除
65    }
66    echo "テスト用のファイル、ディレクトリ、およびアーカイブをクリーンアップしました。\n";
67}
68
69/**
70 * 指定されたディレクトリの内容からTARアーカイブを作成するサンプル関数です。
71 * PharData::buildFromIterator メソッドを使用します。
72 *
73 * システムエンジニアを目指す初心者の方にも理解しやすいように、
74 * テストファイルの作成からアーカイブ、クリーンアップまでの一連の流れを示します。
75 *
76 * @return void
77 */
78function createTarArchiveFromDirectoryExample(): void
79{
80    // アーカイブに含める元のファイルを配置する一時ディレクトリのパス
81    $sourceDirectory = __DIR__ . '/source_files_for_archive_test';
82    // 作成するTARアーカイブのファイル名とパス
83    $archiveFileName = __DIR__ . '/my_archive.tar';
84
85    // 1. アーカイブ作成のためのテスト用ファイルとディレクトリを準備します。
86    setupTestFiles($sourceDirectory);
87
88    try {
89        // 2. PharData オブジェクトを初期化します。
90        //    新しいアーカイブを作成する場合、ファイルを指定します。
91        //    もし同じ名前のファイルが既存であれば、上書きされます。
92        //    PharDataは、一般的なTARやZIP形式のアーカイブを作成・操作するために使用されます。
93        $phar = new PharData($archiveFileName);
94
95        // 3. アーカイブに含めるファイルやディレクトリを走査するためのイテレータを作成します。
96        //    RecursiveDirectoryIterator は、指定されたディレクトリとそのサブディレクトリの
97        //    内容を再帰的に取得するためのものです。
98        //    RecursiveDirectoryIterator::SKIP_DOTS フラグは、'.' (カレントディレクトリ)
99        //    と '..' (親ディレクトリ) のエントリをスキップするために使用します。
100        $iterator = new RecursiveIteratorIterator(
101            new RecursiveDirectoryIterator($sourceDirectory, RecursiveDirectoryIterator::SKIP_DOTS)
102        );
103
104        // 4. buildFromIterator メソッドを呼び出してアーカイブを作成します。
105        //    このメソッドは、イテレータが提供するすべてのファイルをアーカイブに追加します。
106        //    第一引数 ($iterator): アーカイブに追加するファイルへのパスを提供するイテレータ。
107        //    第二引数 ($sourceDirectory): オプション。アーカイブ内のファイルのパスを
108        //                                 相対化するための基準ディレクトリです。
109        //                                 例えば、$sourceDirectoryが '/var/www/source_files' で、
110        //                                 イテレータが '/var/www/source_files/file1.txt' を提供した場合、
111        //                                 アーカイブ内では 'file1.txt' として格納されます。
112        echo "\nTARアーカイブの作成を開始します: " . $archiveFileName . "\n";
113        $addedFiles = $phar->buildFromIterator($iterator, $sourceDirectory);
114
115        if (is_array($addedFiles)) {
116            // buildFromIterator は、成功した場合に追加されたファイルの相対パスの配列を返します。
117            echo "TARアーカイブが正常に作成されました。\n";
118            echo "アーカイブに追加されたファイル:\n";
119            foreach ($addedFiles as $fileInArchive) {
120                echo "- " . $fileInArchive . "\n";
121            }
122
123            // 補足: 作成されたアーカイブの内容を読み取る簡単な例
124            // (この部分はコードの冗長性を避けるためコメントアウトしています)
125            /*
126            echo "\n--- 作成されたアーカイブの内容を確認します ---\n";
127            $readPhar = new PharData($archiveFileName);
128            foreach ($readPhar as $file) {
129                echo " - " . $file->getPathname() . "\n";
130            }
131            echo "----------------------------------------------\n";
132            */
133
134        } else {
135            echo "TARアーカイブの作成に失敗しました。\n";
136        }
137
138    } catch (PharException $e) {
139        // Phar拡張関連のエラー（例: 'phar.readonly' 設定が原因の場合など）をキャッチします。
140        echo "エラー: Phar操作中に問題が発生しました - " . $e->getMessage() . "\n";
141    } catch (Exception $e) {
142        // その他の予期せぬエラーをキャッチします。
143        echo "エラー: 予期せぬ問題が発生しました - " . $e->getMessage() . "\n";
144    } finally {
145        // 5. テストで使用した一時ファイルとディレクトリを必ずクリーンアップします。
146        cleanupTestFiles($sourceDirectory, $archiveFileName);
147    }
148}
149
150// サンプル関数を実行して、TARアーカイブ作成処理を開始します。
151createTarArchiveFromDirectoryExample();
152
153?>

PharData::buildFromIteratorメソッドは、PHPでTARやZIP形式などのアーカイブファイルを効率的に作成する際に利用されます。このメソッドを使用すると、複数のファイルやディレクトリをイテレータ（データ構造を順番に辿るオブジェクト）を通じて一括でアーカイブに追加できます。

第一引数にはTraversableインターフェースを実装したイテレータ（例: RecursiveIteratorIteratorなど）を渡します。このイテレータは、アーカイブに含めたいファイルやディレクトリへのパスを一つずつ提供し、ディレクトリの内容を再帰的に含めることが可能です。

第二引数$baseDirectoryは任意で、アーカイブ内のファイルパスを相対パスとして格納するための基準ディレクトリを指定します。これにより、アーカイブのルートからの相対的なパスでファイルが保存され、アーカイブの可搬性が向上します。

メソッドは成功した場合、アーカイブに追加されたファイルの相対パスの配列を返します。処理が失敗した場合はbool型のfalseを返します。

提供されたサンプルコードでは、まず一時ディレクトリにテスト用のファイル群を作成します。次に、そのディレクトリを走査するイテレータを準備し、PharData::buildFromIteratorメソッドを用いてこれらのファイルを一つのTARアーカイブにまとめます。最後に、作成したアーカイブと一時ファイルをクリーンアップし、ファイル群を簡単にアーカイブする一連の流れを初心者向けに示しています。

Copy
1<?php
2
3/**
4 * PharData::buildFromIterator() メソッドを使用して、イテレータからPHARデータアーカイブを作成する例。
5 *
6 * この関数は、一時的なディレクトリとファイルを作成し、それらをRecursiveDirectoryIteratorと
7 * RecursiveIteratorIteratorで走査し、その結果をPharDataアーカイブにパッケージ化します。
8 * 最後に、作成したアーカイブと一時ファイルをクリーンアップします。
9 *
10 * @return bool アーカイブの作成と検証が成功した場合は true、それ以外は false。
11 */
12function createPharArchiveFromIterator(): bool
13{
14    // 一時ディレクトリのパスを生成
15    $tempSourceDir = sys_get_temp_dir() . DIRECTORY_SEPARATOR . 'my_archive_source_' . uniqid();
16    // 出力されるアーカイブのパスを定義
17    $archivePath = sys_get_temp_dir() . DIRECTORY_SEPARATOR . 'my_archive_' . uniqid() . '.tar';
18
19    try {
20        // 1. アーカイブ元となる一時ファイルとディレクトリを作成
21        echo "一時ディレクトリを作成: {$tempSourceDir}\n";
22        mkdir($tempSourceDir);
23        file_put_contents($tempSourceDir . DIRECTORY_SEPARATOR . 'file1.txt', 'Hello from file1!');
24
25        $subDir = $tempSourceDir . DIRECTORY_SEPARATOR . 'sub';
26        mkdir($subDir);
27        file_put_contents($subDir . DIRECTORY_SEPARATOR . 'file2.txt', 'Content of file2 in a subdirectory.');
28        file_put_contents($subDir . DIRECTORY_SEPARATOR . 'file3.txt', 'Another file here.');
29
30        echo "ソースファイルを作成しました。\n";
31
32        // 2. ディレクトリを走査するためのイテレータを準備
33        // RecursiveDirectoryIterator は指定されたディレクトリの項目を走査します。
34        // RecursiveIteratorIterator は、サブディレクトリも再帰的に走査するために使用します。
35        $directoryIterator = new RecursiveDirectoryIterator(
36            $tempSourceDir,
37            RecursiveDirectoryIterator::SKIP_DOTS // . と .. をスキップ
38        );
39        $iterator = new RecursiveIteratorIterator($directoryIterator);
40
41        // 3. PharData オブジェクトを作成
42        // PharData は .tar または .zip 形式のアーカイブを扱います。
43        // ここでは .tar 形式を指定します。
44        echo "アーカイブ '{$archivePath}' の作成を開始します...\n";
45        $phar = new PharData($archivePath);
46
47        // 4. buildFromIterator メソッドを使用してアーカイブを構築
48        // 第二引数 ($baseDirectory) は、アーカイブ内のファイルパスを決定するために重要です。
49        // $tempSourceDir を指定することで、アーカイブ内のファイルパスは
50        // $tempSourceDir を基準とした相対パスになります (例: 'file1.txt', 'sub/file2.txt')。
51        $addedFiles = $phar->buildFromIterator($iterator, $tempSourceDir);
52
53        if ($addedFiles === false) {
54            echo "エラー: アーカイブの構築に失敗しました。\n";
55            return false;
56        }
57
58        echo "アーカイブが正常に構築されました！ 追加されたファイル数: " . count($addedFiles) . "件。\n";
59        echo "追加されたファイル（アーカイブ内パス）:\n";
60        foreach ($addedFiles as $filePathInArchive => $originalFilePath) {
61            echo "- " . $filePathInArchive . " (元のパス: " . $originalFilePath . ")\n";
62        }
63
64        // 5. オプション: 作成されたアーカイブの内容を検証
65        echo "\n作成されたアーカイブ '{$archivePath}' の内容を検証します:\n";
66        $pharArchive = new PharData($archivePath);
67        $pharIterator = new RecursiveIteratorIterator($pharArchive);
68        foreach ($pharIterator as $file) {
69            if ($file->isFile()) {
70                echo "- " . $file->getPathname() . "\n";
71            }
72        }
73
74        return true;
75
76    } catch (Exception $e) {
77        echo "例外が発生しました: " . $e->getMessage() . "\n";
78        return false;
79    } finally {
80        // 6. クリーンアップ
81        echo "\nクリーンアップを開始します。\n";
82
83        // 作成されたアーカイブファイルを削除
84        if (file_exists($archivePath)) {
85            unlink($archivePath);
86            echo "アーカイブファイル '{$archivePath}' を削除しました。\n";
87        }
88
89        // 一時ディレクトリと内容を削除
90        if (file_exists($tempSourceDir)) {
91            // ディレクトリを再帰的に削除するヘルパー関数を使用
92            removeDirectory($tempSourceDir);
93            echo "一時ソースディレクトリ '{$tempSourceDir}' を削除しました。\n";
94        }
95    }
96}
97
98/**
99 * 指定されたディレクトリとその内容を再帰的に削除するヘルパー関数。
100 *
101 * @param string $dir 削除するディレクトリのパス。
102 * @return bool 削除が成功した場合は true、それ以外は false。
103 */
104function removeDirectory(string $dir): bool
105{
106    if (!is_dir($dir)) {
107        return false;
108    }
109
110    $items = array_diff(scandir($dir), ['.', '..']);
111    foreach ($items as $item) {
112        $path = $dir . DIRECTORY_SEPARATOR . $item;
113        if (is_dir($path)) {
114            removeDirectory($path);
115        } else {
116            unlink($path);
117        }
118    }
119    return rmdir($dir);
120}
121
122// 関数を実行
123createPharArchiveFromIterator();
124
125?>

PharData::buildFromIterator()メソッドは、PHPでファイルやディレクトリをまとめて、tarやzipなどのアーカイブファイルを作成する際に利用します。特に、多数のファイルや複雑なディレクトリ構造を効率的にアーカイブに格納するのに適しています。

第一引数の$iteratorには、アーカイブに含めるファイルやディレクトリの情報を順に提供する「イテレータ」オブジェクトを渡します。サンプルコードでは、RecursiveDirectoryIteratorとRecursiveIteratorIteratorを組み合わせて使用し、指定したディレクトリ内のすべてのファイルやサブディレクトリを再帰的に走査しています。これにより、アーカイブに含めるべき内容を自動的に収集できます。

第二引数$baseDirectoryはオプションですが、アーカイブ内のファイルパスを決定する上で重要です。この引数に元のファイルがあるベースディレクトリのパスを指定すると、アーカイブ内のファイルパスはそのベースディレクトリからの相対パスとして格納されます。例えば、/path/to/source/file.txtというファイルを/path/to/sourceを$baseDirectoryとしてアーカイブすると、アーカイブ内ではfile.txtとして保存され、不必要なパス情報を除去できます。

このメソッドは、アーカイブの構築に成功した場合、追加されたファイルのリストを連想配列（アーカイブ内のパス => 元のパス）で返します。構築が失敗した場合はfalseが返されるため、エラーの検出が可能です。サンプルコードでは、一時ファイルを作成し、それらをイテレータでまとめてアーカイブに格納し、最後にクリーンアップするという一連の流れを示しており、ファイルのバックアップや配布パッケージ作成などに応用できます。