【PHP8.x】PharData::NEW_CURRENT_AND_KEY定数の使い方

Copy
1<?php
2
3/**
4 * PharData::NEW_CURRENT_AND_KEY 定数の使用例を示す関数。
5 *
6 * この定数は、PharData::buildFromIterator メソッドで使用され、
7 * アーカイブに追加されるファイルのキーの形式を制御します。
8 * 具体的には、アーカイブ内のファイルパス（キー）が、元のディレクトリからの
9 * 相対パス全体になるように指示します。これは主に、イテレータがデフォルトで
10 * ファイル名のみをキーとして返す場合に、その挙動を上書きするために使用されます。
11 */
12function demonstratePharDataNewCurrentAndKey(): void
13{
14    // 1. 一時ディレクトリとファイルの準備
15    $tempDir = __DIR__ . '/phar_example_files';
16    $subDir = $tempDir . '/documents';
17    $archiveName = __DIR__ . '/my_project_archive.tar';
18
19    // 既存のアーカイブとディレクトリをクリーンアップ
20    if (file_exists($archiveName)) {
21        unlink($archiveName);
22    }
23    if (file_exists($archiveName . '.gz')) {
24        unlink($archiveName . '.gz');
25    }
26    if (is_dir($subDir)) {
27        array_map('unlink', glob("$subDir/*.*"));
28        rmdir($subDir);
29    }
30    if (is_dir($tempDir)) {
31        array_map('unlink', glob("$tempDir/*.*"));
32        rmdir($tempDir);
33    }
34
35    mkdir($subDir, 0777, true);
36
37    file_put_contents($tempDir . '/README.md', 'プロジェクトの概要ファイルです。');
38    file_put_contents($subDir . '/report.txt', '年間レポートの内容です。');
39    file_put_contents($subDir . '/notes.txt', '重要なメモ。');
40
41    echo "--- アーカイブ対象のファイル構造 ---\n";
42    echo realpath($tempDir) . "/README.md\n";
43    echo realpath($subDir) . "/report.txt\n";
44    echo realpath($subDir) . "/notes.txt\n\n";
45
46    try {
47        // 注: Pharアーカイブを作成するには、php.ini で 'phar.readonly = 0' に設定されている必要があります。
48
49        // 2. PharDataオブジェクトを作成
50        // '.tar' 拡張子を指定してtarアーカイブを作成します。
51        $phar = new PharData($archiveName);
52
53        // 3. SplFileInfo オブジェクトのイテレータを作成
54        // RecursiveDirectoryIterator を使ってディレクトリを再帰的に走査します。
55        $iterator = new RecursiveIteratorIterator(
56            new RecursiveDirectoryIterator($tempDir, FilesystemIterator::SKIP_DOTS),
57            RecursiveIteratorIterator::LEAVES_ONLY
58        );
59
60        // 4. buildFromIterator メソッドを使用してイテレータからファイルを追加
61        // buildFromIterator ( Iterator $iterator [, string $baseDirectory = "" [, string $directoryPrefix = "" [, int $flags = 0 ]]] )
62        //
63        // 第1引数: ファイルを提供するイテレータ（今回は RecursiveIteratorIterator）
64        // 第2引数: アーカイブ内のキーから削除するベースディレクトリのパス。
65        //          $tempDir を指定することで、キーがこのパスからの相対パスになります。
66        // 第3引数: アーカイブ内のファイルのキーに付与するプレフィックス。
67        //          'my_project_root/' と指定することで、全てのキーの前にこの文字列が付きます。
68        // 第4引数: オプションのフラグ。PharData::NEW_CURRENT_AND_KEY を指定することで、
69        //          アーカイブ内のキーが元のディレクトリからの相対パス（フルパス）になります。
70        //          このフラグがない場合、特定のイテレータによってはキーがファイル名のみになることがあります。
71        $phar->buildFromIterator(
72            $iterator,
73            $tempDir, // キーからこのパスを削除し、相対パスにする
74            'my_project_root', // キーにこのプレフィックスを追加
75            PharData::NEW_CURRENT_AND_KEY // キーを元のディレクトリからの相対パスにするフラグ
76        );
77
78        echo "--- 作成されたアーカイブ '" . basename($archiveName) . "' の内容 ---\n";
79        echo "キーの形式が 'my_project_root/元のディレクトリからの相対パス' となります。\n";
80        foreach ($phar as $file) {
81            // ここで $file->getPathname() がアーカイブ内のキー（プレフィックス付きの相対パス）になります
82            echo "  - " . $file->getPathname() . "\n";
83        }
84        echo "\n";
85
86        // 必要であれば、作成したアーカイブを圧縮することもできます。
87        // $phar->compress(Phar::GZ);
88        // echo "アーカイブが圧縮されました: " . basename($archiveName . '.gz') . "\n";
89
90    } catch (Exception $e) {
91        echo "エラーが発生しました: " . $e->getMessage() . "\n";
92        echo "ヒント: 'phar.readonly' が 'Off' (0) に設定されているか確認してください。\n";
93        echo "    php.ini の設定で 'phar.readonly = 0' とする必要があります。\n";
94    } finally {
95        // 5. 後処理: 作成したファイルとディレクトリを削除
96        if (file_exists($archiveName)) {
97            unlink($archiveName);
98        }
99        if (file_exists($archiveName . '.gz')) {
100            unlink($archiveName . '.gz');
101        }
102        if (is_dir($subDir)) {
103            array_map('unlink', glob("$subDir/*.*"));
104            rmdir($subDir);
105        }
106        if (is_dir($tempDir)) {
107            array_map('unlink', glob("$tempDir/*.*"));
108            rmdir($tempDir);
109        }
110        echo "一時ファイルとディレクトリがクリーンアップされました。\n";
111    }
112}
113
114// 関数の実行
115demonstratePharDataNewCurrentAndKey();

PharData::NEW_CURRENT_AND_KEYは、PHPのPhar拡張機能で提供される定数の一つです。この定数は、主にPharDataクラスのbuildFromIteratorメソッドで使用され、アーカイブに追加されるファイルのキー（アーカイブ内部でのファイルパス）の形式を制御します。

具体的には、buildFromIteratorメソッドに渡されるイテレータ（例えばRecursiveIteratorIterator）は、デフォルトでファイル名のみをキーとして返すことがあります。しかし、PharData::NEW_CURRENT_AND_KEY定数をbuildFromIteratorメソッドの第4引数（フラグ）として指定すると、アーカイブ内のキーが、元のファイルが存在したディレクトリからの相対パス全体を含む形式になります。

例えば、source/documents/report.txtというファイルをアーカイブに追加する際、この定数を使用しないとキーがreport.txtとなる場合がありますが、定数を指定するとdocuments/report.txtのような相対パスになります。これにより、元のディレクトリ構造を反映した状態でファイルをアーカイブ化でき、特に複数のディレクトリに分散したファイルを効率的にまとめる場合に非常に有効です。この定数自体には、メソッドのように引数をとったり特定の値を戻したりする機能はありません。

Copy
1<?php
2
3/**
4 * PharDataアーカイブの作成、抽出、および関連定数 (PharData::NEW_CURRENT_AND_KEY) の
5 * 使用例を示します。
6 *
7 * この関数は、システムエンジニアを目指す初心者が、`new` キーワードや括弧を
8 * 使用したオブジェクトのインスタンス化、およびPharData定数の利用方法を理解できるように
9 * 設計されています。
10 *
11 * PharData::NEW_CURRENT_AND_KEY は、抽出時に既存のファイルを更新し、
12 * アーカイブにないファイルはそのまま残す動作を指示するフラグです。
13 *
14 * @return void
15 */
16function demonstratePharDataExtraction(): void
17{
18    // 現在のスクリプトがあるディレクトリを基準とする一時パスを設定
19    $baseDir = __DIR__;
20    $tempSourceDir = $baseDir . '/temp_source_for_phar';
21    $archiveFileTar = $baseDir . '/my_archive.tar';
22    $extractDestinationDir = $baseDir . '/extracted_destination';
23
24    // 実行前後のクリーンアップを行うヘルパー関数
25    $cleanup = function () use ($archiveFileTar, $tempSourceDir, $extractDestinationDir) {
26        if (file_exists($archiveFileTar)) {
27            unlink($archiveFileTar);
28        }
29        // ディレクトリを再帰的に削除する
30        $rmdirRecursive = function ($dir) use (&$rmdirRecursive) {
31            if (!is_dir($dir)) return; // ディレクトリが存在しない場合は何もしない
32            foreach (new DirectoryIterator($dir) as $fileInfo) {
33                if ($fileInfo->isDot()) continue; // . と .. はスキップ
34                if ($fileInfo->isDir()) {
35                    $rmdirRecursive($fileInfo->getPathname()); // サブディレクトリを再帰的に削除
36                } else {
37                    unlink($fileInfo->getPathname()); // ファイルを削除
38                }
39            }
40            rmdir($dir); // 空になったディレクトリを削除
41        };
42        $rmdirRecursive($tempSourceDir);
43        $rmdirRecursive($extractDestinationDir);
44    };
45
46    // 最初に一時ファイルやディレクトリをクリーンアップ
47    $cleanup();
48    echo "--- 処理開始 ---\n";
49
50    try {
51        // STEP 1: 抽出元となるダミーのディレクトリとファイルを作成
52        echo "テスト用のソースディレクトリ '{$tempSourceDir}' を作成中...\n";
53        mkdir($tempSourceDir);
54        file_put_contents("$tempSourceDir/file1.txt", "Content from archive: File 1.");
55        file_put_contents("$tempSourceDir/file2.txt", "Content from archive: File 2.");
56        mkdir("$tempSourceDir/subdir");
57        file_put_contents("$tempSourceDir/subdir/subfile.txt", "Content from archive: Subfile.");
58
59        // STEP 2: Pharアーカイブファイル (.tar形式) を作成
60        // `new` キーワードと括弧を使ってPharオブジェクトをインスタンス化します。
61        // これにより、Pharアーカイブを新規に作成または既存のものを開く準備をします。
62        echo "Pharアーカイブ '{$archiveFileTar}' を作成中...\n";
63        $phar = new Phar($archiveFileTar); // PHPの 'new' と '括弧' の使用例 (Pharアーカイブの作成)
64        // アーカイブの変更をバッファリング開始 (パフォーマンス向上と安全な変更のため)
65        $phar->startBuffering();
66        // 作成したダミーディレクトリの内容をアーカイブに追加します
67        $phar->buildFromDirectory($tempSourceDir);
68        // 作成したPharアーカイブを .tar 形式に変換します
69        $phar->convertToData(Phar::TAR);
70        // バッファリングを終了し、変更をファイルに書き込みます
71        $phar->stopBuffering();
72        unset($phar); // Pharオブジェクトを解放し、ファイルロックを解除
73
74        // STEP 3: 抽出先ディレクトリを作成し、PharData::NEW_CURRENT_AND_KEY の動作を確認するための
75        // 既存ファイルを準備します。
76        echo "抽出先ディレクトリ '{$extractDestinationDir}' と既存ファイルを準備中...\n";
77        mkdir($extractDestinationDir);
78        // このファイル (`file1.txt`) はアーカイブにも存在するため、抽出時にアーカイブの内容で更新されるはずです。
79        file_put_contents("$extractDestinationDir/file1.txt", "OLD content of File 1 in destination.");
80        // このファイル (`existing_only.txt`) はアーカイブに存在しないため、抽出後もそのまま残るはずです。
81        file_put_contents("$extractDestinationDir/existing_only.txt", "This file should remain untouched.");
82
83        // STEP 4: PharData オブジェクトをインスタンス化し、アーカイブを抽出
84        // `new` キーワードと括弧を使ってPharDataオブジェクトをインスタンス化します。
85        // これにより、データ形式のPharアーカイブ (.tar, .zipなど) を操作できます。
86        echo "PharDataオブジェクトをインスタンス化し、アーカイブから抽出中...\n";
87        $pharData = new PharData($archiveFileTar); // PHPの 'new' と '括弧' の別の使用例 (PharDataオブジェクトのインスタンス化)
88
89        // STEP 5: PharData::extractTo() メソッドで PharData::NEW_CURRENT_AND_KEY 定数を使用
90        // この定数 (PharData::NEW_CURRENT_AND_KEY) は、
91        // 抽出時に「既存のファイルを上書き更新し、アーカイブにないファイルは削除せずそのまま残す」
92        // という挙動を指示します。
93        echo "PharData::NEW_CURRENT_AND_KEY を使用して '{$extractDestinationDir}' に抽出中...\n";
94        // extractTo(string $pathto, array|string|null $files = null, bool $overwrite = false, int $flags = 0): bool
95        // 第3引数 `true` で既存ファイルの上書きを許可し、第4引数でフラグを指定します。
96        $pharData->extractTo($extractDestinationDir, null, true, PharData::NEW_CURRENT_AND_KEY);
97
98        echo "\n--- 抽出完了 --- \n";
99        echo "抽出ディレクトリ '{$extractDestinationDir}' の内容:\n";
100        // 抽出後のディレクトリ内容を再帰的に表示して結果を確認
101        $rii = new RecursiveIteratorIterator(new RecursiveDirectoryIterator($extractDestinationDir, FilesystemIterator::SKIP_DOTS), RecursiveIteratorIterator::LEAVES_ONLY);
102        foreach ($rii as $file) {
103            if ($file->isFile()) {
104                $relativePath = substr($file->getPathname(), strlen($extractDestinationDir) + 1);
105                echo "  - " . $relativePath . " (内容: " . file_get_contents($file->getPathname()) . ")\n";
106            }
107        }
108        echo "\n--- 期待される結果 ---\n";
109        echo "  - file1.txt: アーカイブの内容 (\"Content from archive: File 1.\") に更新されている\n";
110        echo "  - file2.txt: 新しく追加されている\n";
111        echo "  - subdir/subfile.txt: 新しく追加されている (サブディレクトリ内のファイル)\n";
112        echo "  - existing_only.txt: 抽出前の内容 (\"This file should remain untouched.\") で残っている\n";
113
114    } catch (PharException $e) {
115        echo "Phar 操作中にエラーが発生しました: " . $e->getMessage() . "\n";
116        echo "ヒント: PHPの 'phar' 拡張機能が有効になっているか確認してください。\n";
117        echo "       また、php.iniで 'phar.readonly = Off' に設定が必要な場合があります。\n";
118    } catch (Exception $e) {
119        echo "予期せぬエラーが発生しました: " . $e->getMessage() . "\n";
120    } finally {
121        // 実行後のクリーンアップ
122        echo "\nクリーンアップ中...\n";
123        $cleanup();
124        echo "クリーンアップ完了。\n";
125        echo "--- 処理終了 ---\n";
126    }
127}
128
129// サンプルコードの実行
130demonstratePharDataExtraction();
131
132?>

このサンプルコードは、PHPにおけるnewキーワードと括弧を使用したオブジェクトのインスタンス化、およびPharDataクラスのNEW_CURRENT_AND_KEY定数の利用方法を、システムエンジニアを目指す初心者向けに解説しています。

newキーワードは、クラスから新しいオブジェクトを生成する際に使用され、括弧内にはそのオブジェクトを初期化するための引数を指定します。これにより、例えばPharやPharDataといったクラスの機能を実際に利用するための準備が整います。

PharData::NEW_CURRENT_AND_KEYは、PHPのPhar拡張機能に含まれるPharDataクラスの定数です。この定数は、アーカイブファイル（例：.tarファイル）からファイルを抽出する際の動作を制御するフラグとして機能します。特に、抽出先に既に存在するファイルをアーカイブの内容で上書き更新し、同時にアーカイブに含まれていない既存のファイルは削除せずそのまま保持するという挙動を示します。これにより、既存の環境を保ちつつ、必要なファイルのみを効率的に更新することが可能です。この定数自体は値を持ち、引数や戻り値は持ちません。