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

Copy
1<?php
2
3// 一時的なPharアーカイブファイル名
4$pharFile = __DIR__ . '/my_archive.phar';
5// アーカイブに含めるコンテンツを格納するための一時ディレクトリ
6$tempDir = __DIR__ . '/temp_files_for_phar';
7
8// スクリプト終了時に生成された一時ファイルやディレクトリをクリーンアップする関数を登録します。
9register_shutdown_function(function () use ($pharFile, $tempDir) {
10    if (file_exists($pharFile)) {
11        unlink($pharFile);
12    }
13    // Pharアーカイブは形式によって追加のファイルが生成される場合があります。
14    if (file_exists($pharFile . '.zip')) { // ZIP形式の場合の例
15        unlink($pharFile . '.zip');
16    }
17    if (file_exists($pharFile . '.tar')) { // TAR形式の場合の例
18        unlink($pharFile . '.tar');
19    }
20    // 一時ディレクトリ内のファイルとディレクトリを削除
21    if (is_dir($tempDir)) {
22        $files = glob($tempDir . '/*');
23        foreach ($files as $file) {
24            if (is_file($file)) {
25                unlink($file);
26            }
27        }
28        rmdir($tempDir);
29    }
30});
31
32try {
33    // Pharアーカイブに含めるための一時ディレクトリとファイルを作成します。
34    if (!is_dir($tempDir)) {
35        mkdir($tempDir, 0777, true); // 親ディレクトリも再帰的に作成
36    }
37    file_put_contents($tempDir . '/document.txt', 'This is a sample document.');
38    file_put_contents($tempDir . '/sub/image.jpg', 'fake image content'); // サブディレクトリ内のファイル
39
40    // Pharアーカイブを作成します（書き込みモード）。
41    // NOTE: Phar拡張を動作させるには、php.ini で 'phar.readonly = 0' の設定が必要です。
42    // PHP CLI で実行する場合、'php -d phar.readonly=0 your_script.php' のように指定することもできます。
43    $phar = new Phar($pharFile);
44    $phar->startBuffering(); // バッファリングを開始し、効率的にファイルを追加
45    // 一時ディレクトリの内容をPharアーカイブに追加します。
46    // 第二引数を省略すると、指定ディレクトリ内のすべてのファイルがアーカイブされます。
47    $phar->buildFromDirectory($tempDir);
48    $phar->setStub($phar->createDefaultStub('index.php')); // デフォルトの実行スタブを設定
49    $phar->stopBuffering(); // バッファリングを停止し、Pharアーカイブを確定
50
51    echo "Pharアーカイブ内のキー（ファイルパス）の取得例:\n";
52
53    // 作成したPharアーカイブを読み込みモードで開き、その内容をイテレートします。
54    // 各エントリのキー（アーカイブ内のファイルパス）を取得します。
55    // Phar::KEY_AS_PATHNAME定数は、Pharアーカイブのエントリをキーとして取得する際に、
56    // パス名の形式（例: 相対パスか絶対パスか）に影響を与える定数であると推測されます。
57    // (標準のPHP Pharライブラリでは、この定数を直接受け取るメソッドは公開されていませんが、概念的な意味として理解してください。)
58    $pharReader = new Phar($pharFile); // 読み込みモードでPharを再オープン
59
60    foreach ($pharReader as $key => $fileInfo) {
61        // $key 変数には、Pharアーカイブ内のエントリの相対パス名が含まれます。
62        echo "- キー: " . $key . "\n";
63        // $fileInfo は PharFileInfo オブジェクトで、ファイルのサイズなどの詳細情報にアクセスできます。
64        // 例: echo "  - サイズ: " . $fileInfo->getSize() . "バイト\n";
65    }
66
67} catch (PharException $e) {
68    // Phar固有のエラーが発生した場合の処理
69    echo "Phar操作エラー: " . $e->getMessage() . "\n";
70} catch (Exception $e) {
71    // その他の一般的なエラーが発生した場合の処理
72    echo "一般エラー: " . $e->getMessage() . "\n";
73}

このサンプルコードは、PHPのPhar拡張機能でPharアーカイブを作成し、そのアーカイブ内のファイルパス（キー）を取得する方法を示しています。

Phar::KEY_AS_PATHNAME定数は、Pharアーカイブ内のエントリを識別する際、そのパス名をキーとして扱う概念を表します。この定数自体に引数も戻り値もありません。

コードでは、まず一時ディレクトリにファイルを作成し、これらをbuildFromDirectory()メソッドでPharアーカイブに追加します。その後、作成したPharを読み込みモードで再度開き、foreachループでアーカイブ内の各エントリを順に処理します。このループにおいて、$key変数にはPharアーカイブ内のエントリの相対パス名（例: document.txtやsub/image.jpg）が格納されます。アーカイブにどのようなファイルが、どのパスで含まれているかを正確に確認できます。

キー取得は、アーカイブ内の特定ファイルへのアクセスに重要です。Phar拡張機能を利用するには、php.iniでphar.readonly = 0の設定が必要です。

Copy
1<?php
2
3/**
4 * Pharアーカイブ内のファイルのキー形式がどのように変化するかを示すサンプルコード。
5 *
6 * システムエンジニアを目指す初心者向けに、Phar::KEY_AS_PATHNAME 定数が、
7 * Pharアーカイブをイテレートする際のキー（ファイル名やパス名）の形式に
8 * どのように影響するかを具体的に示します。
9 */
10function demonstratePharKeyBehavior(): void
11{
12    // 一時ファイルとディレクトリの準備
13    $pharPath = __DIR__ . '/example.phar';
14    $tempDir = __DIR__ . '/temp_files_for_phar';
15    $subDir = $tempDir . '/my_subdir';
16
17    // ディレクトリを作成
18    @mkdir($tempDir, 0777, true);
19    @mkdir($subDir, 0777, true);
20
21    // テストファイルを作成
22    file_put_contents($tempDir . '/file_a.txt', 'This is file A.');
23    file_put_contents($subDir . '/file_b.txt', 'This is file B.');
24
25    echo "--- Pharアーカイブ作成とキーのデフォルト動作の準備 ---" . PHP_EOL;
26
27    try {
28        // 新しいPharアーカイブを作成します。
29        // 既存のアーカイブがある場合は上書きされます。
30        $phar = new Phar($pharPath);
31
32        // Pharアーカイブの書き込みをバッファリングします。
33        $phar->startBuffering();
34
35        // ファイルをアーカイブに追加します。
36        // 第二引数はアーカイブ内でファイルが持つ名前（キー）です。
37        $phar->addFile($tempDir . '/file_a.txt', 'file_a.txt');
38        $phar->addFile($subDir . '/file_b.txt', 'my_subdir/file_b.txt');
39
40        // デフォルトのスタブ（Pharを実行するためのPHPコード）を設定します。
41        $phar->setStub($phar->createDefaultStub('index.php'));
42
43        // Pharアーカイブの書き込みを終了し、保存します。
44        $phar->stopBuffering();
45
46        echo "Pharアーカイブを作成しました: " . realpath($pharPath) . PHP_EOL;
47        echo PHP_EOL;
48
49        // ----------------------------------------------------
50        // 1. デフォルトのキー形式（Phar::KEY_AS_PATHNAME に相当）
51        // ----------------------------------------------------
52        // Pharオブジェクトを直接イテレートすると、デフォルトでキーは
53        // アーカイブ内の相対パス（Phar::KEY_AS_PATHNAME と同じ挙動）になります。
54        echo "1. デフォルトのキー形式（Phar::KEY_AS_PATHNAME と同じ）:" . PHP_EOL;
55        foreach ($phar as $key => $file) {
56            echo "  キー: " . $key . PHP_EOL; // 例: file_a.txt, my_subdir/file_b.txt
57        }
58        echo PHP_EOL;
59
60        // ----------------------------------------------------
61        // 2. Phar::KEY_AS_FILENAME を設定した場合
62        // ----------------------------------------------------
63        // Phar::setFlags() を使用して、イテレーション時のキー形式を変更します。
64        // Phar::KEY_AS_FILENAME を設定すると、キーはファイル名のみになります。
65        // パス情報が含まれていたとしても、ファイル名だけがキーとして使われます。
66        $phar->setFlags(Phar::KEY_AS_FILENAME);
67        echo "2. Phar::KEY_AS_FILENAME を設定した場合（キーがファイル名のみ）:" . PHP_EOL;
68        foreach ($phar as $key => $file) {
69            echo "  キー: " . $key . PHP_EOL; // 例: file_a.txt, file_b.txt
70        }
71        echo PHP_EOL;
72
73        // ----------------------------------------------------
74        // 3. Phar::KEY_AS_PATHNAME を設定した場合
75        // ----------------------------------------------------
76        // Phar::KEY_AS_PATHNAME を設定すると、キーはアーカイブ内の相対パスになります。
77        // これはデフォルトの挙動と同じです。
78        $phar->setFlags(Phar::KEY_AS_PATHNAME);
79        echo "3. Phar::KEY_AS_PATHNAME を設定した場合（キーが相対パス名）:" . PHP_EOL;
80        foreach ($phar as $key => $file) {
81            echo "  キー: " . $key . PHP_EOL; // 例: file_a.txt, my_subdir/file_b.txt
82        }
83        echo PHP_EOL;
84
85    } catch (PharException $e) {
86        // Phar操作中に発生した例外を捕捉します。
87        echo "Phar操作中にエラーが発生しました: " . $e->getMessage() . PHP_EOL;
88    } finally {
89        // サンプル実行後に作成したファイルとディレクトリをクリーンアップします。
90        echo "--- クリーンアップ ---" . PHP_EOL;
91
92        // Pharオブジェクトをunsetすることで、Pharファイルへのロックを解除します。
93        if (isset($phar)) {
94            unset($phar);
95        }
96
97        // Pharアーカイブファイルを削除します。
98        if (file_exists($pharPath)) {
99            unlink($pharPath);
100            echo "Pharアーカイブを削除しました: " . $pharPath . PHP_EOL;
101        }
102
103        // 作成した一時ファイルを削除します。
104        @unlink($tempDir . '/file_a.txt');
105        @unlink($subDir . '/file_b.txt');
106
107        // 空になったディレクトリを削除します。
108        @rmdir($subDir);
109        @rmdir($tempDir);
110        echo "一時ファイルとディレクトリを削除しました。" . PHP_EOL;
111    }
112}
113
114// 関数を実行して動作を確認します。
115demonstratePharKeyBehavior();
116
117?>

Phar::KEY_AS_PATHNAMEは、PHPのPhar拡張機能において、Pharアーカイブファイル内のコンテンツをループ処理する際に、ファイルのキー形式を指定するための定数です。これはPharクラスに所属し、主にPhar::setFlags()メソッドで利用されます。この定数を設定すると、アーカイブ内の各ファイルをイテレートした際に取得できるキーが、そのファイルのアーカイブ内での「相対パス名」として扱われます。例えば、アーカイブ内にmy_subdir/file_b.txtというパスでファイルが存在する場合、イテレーション時のキーはmy_subdir/file_b.txtとなります。これはPharアーカイブをイテレートする際のデフォルトの挙動と同じです。

対照的に、Phar::KEY_AS_FILENAME定数を設定した場合は、キーはファイル名部分のみ（上記の例ではfile_b.txt）となります。このようにKEY_AS_PATHNAMEを使うことで、ファイルがアーカイブ内で持つディレクトリ構造を含んだパスをキーとして利用できるようになります。この定数自体は値を引数として取ることも、特定の値を戻り値として返すこともありません。