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

Copy
1<?php
2
3/**
4 * このスクリプトは、PharData::KEY_AS_FILENAME 定数の使用方法と、
5 * それがPharアーカイブ内のエントリ名（キー）にどのように影響するかを示します。
6 *
7 * Phar::KEY_AS_FILENAME は、Pharアーカイブを作成する際に、
8 * ファイルシステム上のパスではなく、単純なファイル名をアーカイブ内のエントリ名（キー）として使用するよう指定するフラグです。
9 */
10
11// 一時的なディレクトリとファイルを作成し、テストデータを準備します。
12$tempDir = __DIR__ . DIRECTORY_SEPARATOR . 'temp_files_' . uniqid();
13$tempSubDir = $tempDir . DIRECTORY_SEPARATOR . 'subfolder';
14
15// ディレクトリを作成します。
16mkdir($tempDir);
17mkdir($tempSubDir);
18
19// テスト用のファイルを作成します。
20file_put_contents($tempDir . DIRECTORY_SEPARATOR . 'file_a.txt', 'Content of file A');
21file_put_contents($tempSubDir . DIRECTORY_SEPARATOR . 'file_b.txt', 'Content of file B');
22
23// 作成するPharアーカイブのファイルパスを定義します。
24$pharFilePath = __DIR__ . DIRECTORY_SEPARATOR . 'example_data.phar';
25
26// 既存のPharファイルと圧縮ファイルがあれば削除します（テストの再現性を確保するため）。
27if (file_exists($pharFilePath)) {
28    unlink($pharFilePath);
29}
30if (file_exists($pharFilePath . '.gz')) { // 圧縮形式を設定した場合に備えて
31    unlink($pharFilePath . '.gz');
32}
33
34try {
35    // PharDataオブジェクトを作成し、新しいPharアーカイブを準備します。
36    // 第1引数: 作成するPharアーカイブのファイルパス
37    $phar = new PharData($pharFilePath);
38
39    // アーカイブ内のファイルをGZIP形式で圧縮する設定（オプション）。
40    $phar->setCompression(Phar::GZ);
41
42    // 指定されたディレクトリからアーカイブを構築します。
43    // 第1引数: アーカイブに含めるファイルの存在するルートディレクトリ
44    // 第2引数: 含めるファイル名をフィルタリングするための正規表現（ここでは .txt ファイルのみを対象）
45    // 第3引数: アーカイブ内のパスのプレフィックス（通常は null）
46    // 第4引数: オプションフラグ。
47    //          Phar::KEY_AS_FILENAME を指定することで、アーカイブ内の各エントリのキーが、
48    //          元のファイルシステムのパス全体ではなく、そのファイル名（ベース名）になります。
49    $phar->buildFromDirectory(
50        $tempDir,
51        '/\.txt$/',
52        null,
53        Phar::KEY_AS_FILENAME // ここで KEY_AS_FILENAME 定数を使用します
54    );
55
56    echo "Pharアーカイブが作成されました: " . $pharFilePath . "\n\n";
57
58    echo "Pharアーカイブ内のキー名（ファイル名）の取得:\n";
59    // 作成されたPharアーカイブを開き、内部のエントリをループしてキー名を取得します。
60    // PharDataオブジェクトはIteratorAggregateを実装しているため、foreachで直接ループできます。
61    // foreach ($phar as $key => $file) の $key に、Phar::KEY_AS_FILENAME フラグによって設定されたエントリ名が入ります。
62    foreach ($phar as $key => $file) {
63        echo "- " . $key . "\n";
64    }
65
66} catch (PharException $e) {
67    // Phar操作中にエラーが発生した場合の処理
68    echo "Phar操作中にエラーが発生しました: " . $e->getMessage() . "\n";
69} finally {
70    // クリーンアップ: 作成したPharファイルと一時ディレクトリを削除します。
71
72    // Pharファイルを削除
73    if (file_exists($pharFilePath)) {
74        unlink($pharFilePath);
75    }
76    if (file_exists($pharFilePath . '.gz')) {
77        unlink($pharFilePath . '.gz');
78    }
79    
80    // 一時ディレクトリとその内容（サブディレクトリを含む）を削除
81    // RecursiveIteratorIterator を使用して、ディレクトリ内のすべてのファイルとサブディレクトリを再帰的に処理します。
82    $files = new RecursiveIteratorIterator(
83        new RecursiveDirectoryIterator($tempDir, RecursiveDirectoryIterator::SKIP_DOTS),
84        RecursiveIteratorIterator::CHILD_FIRST // 子要素から先に処理することで、空のディレクトリを削除できるようにします。
85    );
86    foreach ($files as $fileinfo) {
87        $todo = ($fileinfo->isDir() ? 'rmdir' : 'unlink'); // ディレクトリかファイルかで実行する関数を切り替えます。
88        $todo($fileinfo->getRealPath());
89    }
90    // 空になった一時ディレクトリを削除
91    if (is_dir($tempDir)) {
92        rmdir($tempDir);
93    }
94    echo "\nクリーンアップが完了しました。\n";
95}

PHPのPhar::KEY_AS_FILENAMEは、Pharアーカイブという形式で複数のファイルを一つにまとめる際に、アーカイブ内のファイル名（キー名）の扱いを指定する定数です。この定数には引数や戻り値はありません。

通常、Pharアーカイブにファイルを追加すると、そのファイルのパス全体がアーカイブ内のキー名として使われます。例えば、「temp_files/subfolder/file_b.txt」というパスで追加した場合、キー名も「subfolder/file_b.txt」となります。しかし、Phar::KEY_AS_FILENAME定数をオプションとして指定すると、パス全体ではなく、ファイルのベース名（例：「file_b.txt」）だけがキー名として使用されるようになります。

サンプルコードでは、PharData::buildFromDirectoryメソッドの第四引数にPhar::KEY_AS_FILENAMEを指定してPharアーカイブを作成しています。これにより、アーカイブ内のファイルエントリは、元のディレクトリ構造を示すパスではなく、単純なファイル名（例：「file_a.txt」、「file_b.txt」）として識別されます。その後、foreachループでアーカイブ内のファイルを走査する際、$key変数にはこの簡略化されたファイル名が格納されるため、アプリケーションでファイル名をより直接的に扱うことが可能になります。

Copy
1<?php
2
3/**
4 * PharData::KEY_AS_FILENAME 定数を使用して、Pharアーカイブにファイルを追加する際に
5 * エントリのキーがファイル名になるように指定するサンプルコードです。
6 * この定数を使うことで、Pharアーカイブ内での「キー名」の扱いを制御し、
7 * ソースディレクトリからの相対パス（ファイル名）がキーとして割り当てられるようになります。
8 * これは、アーカイブにファイルを追加する際の「キー名」の割り当て方法を変更する一例です。
9 */
10function createPharArchiveWithFilenameKeys(): void
11{
12    // 一時的なソースディレクトリとアーカイブファイルのパスを定義します。
13    $baseDir = sys_get_temp_dir() . '/phar_source_dir_' . uniqid();
14    $archivePath = sys_get_temp_dir() . '/my_archive_' . uniqid() . '.tar';
15    $compressedArchivePath = $archivePath . '.gz'; // 圧縮後のパス
16
17    // スクリプト終了時に作成した一時ファイルやディレクトリを自動的にクリーンアップするための処理です。
18    // エラーでスクリプトが中断された場合でも実行され、一時ファイルを残しません。
19    register_shutdown_function(function () use ($baseDir, $archivePath, $compressedArchivePath) {
20        if (file_exists($compressedArchivePath)) {
21            unlink($compressedArchivePath);
22        }
23        if (file_exists($archivePath)) {
24            unlink($archivePath); // 圧縮しなかった場合のために削除を試みる
25        }
26        if (is_dir($baseDir)) {
27            // ディレクトリとその内容を再帰的に削除します。
28            $it = new RecursiveDirectoryIterator($baseDir, RecursiveDirectoryIterator::SKIP_DOTS);
29            $files = new RecursiveIteratorIterator($it, RecursiveIteratorIterator::CHILD_FIRST);
30            foreach ($files as $file) {
31                if ($file->isDir()) {
32                    rmdir($file->getRealPath());
33                } else {
34                    unlink($file->getRealPath());
35                }
36            }
37            rmdir($baseDir);
38        }
39    });
40
41    try {
42        // ソースディレクトリとファイルを作成します。
43        mkdir($baseDir);
44        file_put_contents($baseDir . '/file1.txt', 'これはファイル1の内容です。');
45        file_put_contents($baseDir . '/file2.txt', 'これはファイル2の内容です。');
46        mkdir($baseDir . '/subdir');
47        file_put_contents($baseDir . '/subdir/file3.txt', 'これはサブディレクトリ内のファイル3の内容です。');
48
49        echo "ソースディレクトリとファイルを作成しました:\n";
50        echo "  - " . basename($baseDir) . "/file1.txt\n";
51        echo "  - " . basename($baseDir) . "/file2.txt\n";
52        echo "  - " . basename($baseDir) . "/subdir/file3.txt\n\n";
53
54        // PharData::KEY_AS_FILENAME 定数を使用してPharアーカイブを構築します。
55        // buildFromDirectory() の第4引数にこのフラグを渡すことで、
56        // アーカイブ内の各エントリのキーが、ソースディレクトリからの相対パス（ファイル名）になります。
57        echo "PharData::KEY_AS_FILENAME 定数を使用してPharアーカイブを構築します...\n";
58        $phar = new PharData($archivePath);
59        // buildFromDirectory(ソースディレクトリ, 正規表現フィルタ, エイリアス, フラグ)
60        $phar->buildFromDirectory($baseDir, null, null, PharData::KEY_AS_FILENAME);
61        $phar->compress(Phar::GZ); // 作成したアーカイブをgzipで圧縮します。
62
63        echo "アーカイブ '" . basename($compressedArchivePath) . "' が作成されました。\n\n";
64
65        // 作成されたアーカイブの内容を確認します。
66        // 圧縮されたアーカイブを開く必要がある点に注意してください。
67        echo "アーカイブ内のエントリとそのキー:\n";
68        $pharReader = new PharData($compressedArchivePath);
69        foreach ($pharReader as $key => $file) {
70            echo "  キー: '{$key}' (元のパス: " . $file->getPathname() . ")\n";
71        }
72        echo "\n";
73        echo "PharData::KEY_AS_FILENAME の効果により、アーカイブ内のキーがソースファイルの相対パスとなっています。\n";
74        echo "これにより、アーカイブにファイルを追加する際の「キー名」の割り当て方法が変更されました。\n";
75
76    } catch (PharException $e) {
77        echo "Phar拡張機能のエラーが発生しました: " . $e->getMessage() . "\n";
78        echo "Phar拡張機能が有効になっているか、ファイルパスに問題がないか確認してください。\n";
79    } catch (Exception $e) {
80        echo "予期せぬエラーが発生しました: " . $e->getMessage() . "\n";
81    }
82}
83
84// 関数を実行してサンプルコードの動作を確認します。
85createPharArchiveWithFilenameKeys();
86
87?>

PHP 8のPhar拡張機能で提供されるPharData::KEY_AS_FILENAME定数は、Pharアーカイブを構築する際に、アーカイブ内の各エントリ（ファイルやディレクトリ）に割り当てられる「キー名」の挙動を制御するために使用されます。この定数は、主にPharDataクラスのbuildFromDirectoryメソッドなどの第四引数にフラグとして渡して利用します。

この定数を使用すると、アーカイブにファイルやディレクトリを追加する際、それらのエントリのキーが、ソースディレクトリからの相対パス（ファイル名）として割り当てられるようになります。これにより、デフォルトの挙動とは異なり、アーカイブ内のファイルにアクセスする際のキー名が、元のファイルパスを直接反映したものとなり、直感的な管理が可能になります。

PharData::KEY_AS_FILENAME定数自体には引数はなく、特定の値を返すものでもありません。これは、ある動作モードや設定を有効にするための設定フラグとして機能します。Pharアーカイブを作成する際に、エントリの「キー名」の割り当て方法を変更し、ファイルパスをキーとして利用したい場合に活用されます。