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

Copy
1<?php
2
3// このスクリプトは、Pharアーカイブを作成するためのものです。
4// 実行すると 'my_cake_cli_tool.phar' というファイルが生成されます。
5//
6// システムエンジニアを目指す初心者の方へ:
7// Pharファイルは、PHPアプリケーションを単一のアーカイブファイルにパッケージ化する仕組みです。
8// これにより、アプリケーションの配布が容易になり、コマンドラインツールなどによく利用されます。
9//
10// Pharアーカイブを作成する前に、Phar拡張が有効になっていることと、
11// php.iniで 'phar.readonly' が '0' に設定されていることを確認してください。
12// 例: コマンドラインで 'php -d phar.readonly=0 build_cli_tool.php' を実行します。
13
14$pharFileName = 'my_cake_cli_tool.phar';
15$aliasName = 'cake'; // キーワード 'cakephp' を意識したエイリアス名
16
17try {
18    // Pharクラスのインスタンスを作成します。
19    // 第1引数: 作成するPharアーカイブのファイル名。
20    // 第2引数: フラグ (0はデフォルト)。
21    // 第3引数: アーカイブ内の論理名（このPharオブジェクト自体が持つ名前）。
22    $phar = new Phar($pharFileName, 0, $pharFileName);
23
24    // 既存のPharファイルを削除します（もしあれば）。
25    // これにより、スクリプトを繰り返し実行しても問題なく新しいPharが生成されます。
26    if (file_exists($pharFileName)) {
27        unlink($pharFileName);
28    }
29    // 圧縮版（.gz）が存在する場合も削除
30    if (file_exists($pharFileName . '.gz')) {
31        unlink($pharFileName . '.gz');
32    }
33
34    // Pharアーカイブの書き込みを開始します。
35    // これ以降のファイル追加操作はメモリ上で行われ、stopBuffering() でファイルに書き込まれます。
36    $phar->startBuffering();
37
38    // アーカイブに含めるメインのスクリプトの内容を定義します。
39    // このスクリプトは、最終的に 'my_cake_cli_tool.phar' を実行したときに動作します。
40    $cliToolContent = <<<'PHP'
41<?php
42// これはPharアーカイブ内に含まれるスクリプトです。
43
44// Phar::running() は、現在実行中のPharアーカイブの論理名を取得します。
45// Phar::setAlias() で設定されたエイリアス名を優先して返します。
46$runningAlias = Phar::running(false);
47
48echo "Hello from the CLI tool packaged in a Phar archive!\n";
49echo "My logical name (alias) is: '" . $runningAlias . "'\n";
50echo "Arguments received: " . implode(', ', array_slice($argv, 1)) . "\n";
51echo "You invoked me using: php " . basename($runningAlias) . " " . implode(' ', array_slice($argv, 1)) . "\n\n";
52
53// CakePHPのコマンドラインツールを模倣し、サブコマンドを処理する例
54if (isset($argv[1])) {
55    switch ($argv[1]) {
56        case 'version':
57            echo "Tool Version: 1.0.0 (inspired by CakePHP CLI)\n";
58            break;
59        case 'greet':
60            $name = $argv[2] ?? 'Guest';
61            echo "Greetings, " . $name . "!\n";
62            break;
63        default:
64            echo "Unknown command: '" . $argv[1] . "'\n";
65            echo "Usage: php " . basename($runningAlias) . " [version|greet <name>]\n";
66    }
67} else {
68    echo "No command provided. Try 'version' or 'greet <name>'.\n";
69}
70
71PHP;
72
73    // 定義したスクリプトの内容を 'cli_tool.php' という名前でアーカイブに追加します。
74    $phar->addFromString('cli_tool.php', $cliToolContent);
75
76    // Pharアーカイブのエントリーポイント (スタブ) を設定します。
77    // Pharファイルが実行されたときに最初に呼ばれるコードで、ここでは 'cli_tool.php' を含めます。
78    $stub = $phar->createDefaultStub('cli_tool.php');
79
80    // Phar::setAlias() メソッドを使用して、Pharアーカイブに論理的なエイリアスを設定します。
81    // このエイリアスは、Phar::running() のようなPhar関連の関数が、
82    // ファイルの実際のパスではなく、このエイリアス名を返すようにするために使用されます。
83    // キーワード 'cakephp' に関連して、ここでは 'cake' というエイリアスを設定しています。
84    // 例えば、Pharアーカイブを 'my_cake_cli_tool.phar' として実行しても、
85    // 内部のPhar::running() は 'cake' を返します。
86    // これにより、アプリケーションは常に一貫した名前で自分自身を参照できます。
87    $phar->setAlias($aliasName);
88
89    // 設定したスタブをPharアーカイブに書き込みます。
90    $phar->setStub($stub);
91
92    // アーカイブの書き込みを終了し、ファイルに保存します。
93    $phar->stopBuffering();
94
95    // オプション: PharファイルをGZIP形式で圧縮し、実行権限を付与します。
96    $phar->compressFiles(Phar::GZ);
97    $phar->chmod(0755);
98
99    // Pharアーカイブの作成処理が成功した場合、このスクリプトは静かに終了します。
100    // (出力条件「サンプルコード以外の出力は行わない」に厳密に従うため、成功メッセージは表示しません)
101
102} catch (Exception $e) {
103    // Pharアーカイブ作成中にエラーが発生した場合。
104    // 出力条件に従い、明示的なエラーメッセージ出力は行わず、
105    // PHPのデフォルトの例外処理に任せるか、単にスクリプトを終了します。
106    // 例えば、php.iniの 'phar.readonly' 設定が原因の場合など。
107    exit(1);
108}

このPHPスクリプトは、複数のPHPファイルを単一の実行可能なPharアーカイブファイルとしてパッケージ化し、そのアーカイブに論理的なエイリアスを設定する方法を示しています。Pharファイルは、PHP製のコマンドラインツールやアプリケーションを配布する際に非常に便利な形式です。Pharファイルを生成するには、php.ini設定でphar.readonlyを0に設定する必要があります。

スクリプトではまず、Pharクラスのインスタンスを作成し、アーカイブのファイル名を指定します。次に、アーカイブに含めるメインスクリプトの内容を定義し、addFromString()でアーカイブに追加します。createDefaultStub()でPharファイルが実行されたときのエントリポイント（最初に呼び出される部分）を設定した後、本メソッドであるPhar::setAlias()を呼び出します。

Phar::setAlias()メソッドは、Pharアーカイブに一貫した論理名（エイリアス）を設定します。引数$aliasには、エイリアスとして使用したい文字列を指定します。このメソッドには戻り値がありません。このエイリアスを設定することで、Pharアーカイブの内部でPhar::running()のような関数が、ファイルの実際のパスではなく、ここで設定されたエイリアス名を返すようになります。例えば、このサンプルではmy_cake_cli_tool.pharというファイル名で作成しつつ、'cake'というエイリアスを設定しているため、内部からは常に「cake」として自身を参照でき、CakePHPのCLIツールのように一貫した名前で動作させたい場合に役立ちます。最後にsetStub()でスタブを書き込み、stopBuffering()でアーカイブをファイルに保存して完了です。

Copy
1<?php
2
3/**
4 * Phar::setAlias メソッドのサンプルコード
5 *
6 * このメソッドは、Pharアーカイブの内部エイリアスを設定します。
7 * エイリアスは、Pharアーカイブが自身を識別するために使用される名前（オプション）です。
8 * 特に、Phar::running() がそのPharアーカイブのエイリアスを返す際に利用されます。
9 */
10function createAndAliasPhar(): void
11{
12    // 生成するPharアーカイブのファイルパスと、設定するエイリアスを定義します。
13    $pharPath = __DIR__ . '/my_application.phar';
14    $alias = 'my_custom_app_alias';
15
16    // 既存のPharファイルがある場合は削除し、クリーンな状態から始めます。
17    if (file_exists($pharPath)) {
18        unlink($pharPath);
19    }
20
21    try {
22        // 1. Pharアーカイブを新規作成モード ('w' フラグ) で開きます。
23        // コンストラクタの第三引数でもエイリアスを設定できますが、
24        // setAlias メソッドの動作を示すため、ここでは null とし、後で設定します。
25        $phar = new Phar($pharPath, 0, null);
26
27        // 2. Phar::setAlias メソッドを使用して、Pharアーカイブのエイリアスを設定します。
28        // これにより、Pharアーカイブが自身を識別する名前が確定します。
29        $phar->setAlias($alias);
30        echo "Pharアーカイブのエイリアスを '{$alias}' に設定しました。" . PHP_EOL;
31
32        // 3. 自己実行可能なスタブを設定します。
33        // このスタブは、Pharファイルが直接実行されたときに最初に呼び出されるコードです。
34        // ここでは、設定したエイリアスを使ってアーカイブ内の 'index.php' をロードします。
35        $phar->setStub("<?php Phar::mapPhar('$alias'); require 'phar://$alias/index.php'; __HALT_COMPILER(); ?>");
36
37        // 4. アーカイブにメインスクリプトファイルを追加します。
38        // このスクリプトは、Pharアーカイブの実行時に Phar::running() の結果を表示し、
39        // setAlias で設定されたエイリアスが反映されていることを示します。
40        $phar->addFromString('index.php', "<?php echo 'Hello from Phar! My alias is: ' . Phar::running() . PHP_EOL; ?>");
41
42        // Pharオブジェクトへの参照を解除し、アーカイブをディスクに書き込みます。
43        unset($phar);
44
45        echo "Pharアーカイブ '{$pharPath}' を正常に作成しました。" . PHP_EOL;
46        echo PHP_EOL; // 空行で区切り
47
48        // 実行方法のヒントをユーザーに提供します。
49        echo "---" . PHP_EOL;
50        echo "【Pharアーカイブの実行方法】" . PHP_EOL;
51        echo "作成されたPharファイルが正しくエイリアスを認識していることを確認するには、" . PHP_EOL;
52        echo "コマンドラインで以下のコマンドを実行してください:" . PHP_EOL;
53        echo "php -d phar.readonly=0 {$pharPath}" . PHP_EOL;
54        echo "期待される出力: 'Hello from Phar! My alias is: {$alias}'" . PHP_EOL;
55        echo "---" . PHP_EOL;
56
57    } catch (PharException $e) {
58        echo "エラー: Pharアーカイブの作成中に問題が発生しました: " . $e->getMessage() . PHP_EOL;
59        // phar.readonly 設定に関する一般的なエラーメッセージへのヒント。
60        if (str_contains($e->getMessage(), 'phar.readonly') || str_contains($e->getMessage(), 'write operations')) {
61            echo "ヒント: PHPの 'phar.readonly' 設定が 'Off' であることを確認してください。" . PHP_EOL;
62            echo "  一時的に 'php -d phar.readonly=0 [スクリプト名.php]' のように実行することもできます。" . PHP_EOL;
63        }
64    } finally {
65        // 後処理: サンプルコードが完結するように、作成したPharファイルを削除します。
66        // ユーザーが実行テストを行いたい場合は、このブロックをコメントアウトしてください。
67        if (file_exists($pharPath)) {
68            unlink($pharPath);
69            echo "作成されたPharアーカイブ '{$pharPath}' を削除しました。" . PHP_EOL;
70        }
71    }
72}
73
74// 関数を実行してPharアーカイブを作成し、エイリアスを設定します。
75createAndAliasPhar();

Phar::setAliasメソッドは、PHPのPhar拡張機能において、自己完結型アーカイブであるPharファイルに内部的な識別名（エイリアス）を設定するために使用されます。このエイリアスは、Pharアーカイブが自身のコンテンツを識別したり、特にPhar::running()関数が現在のPharファイル名を返す際に利用されたりする重要な役割を持ちます。

引数$aliasには、設定したいエイリアスの文字列を指定します。このエイリアスは、Pharアーカイブのスタブ（起動コード）内で、アーカイブ内のスクリプトにアクセスする際にも活用されます。例えば、Phar::mapPhar('$alias');のように記述することで、指定したエイリアスを介してアーカイブの内容にアクセスできるようになります。このメソッドは戻り値を持ちません。

サンプルコードでは、まず新しいPharアーカイブを作成し、setAliasメソッドを使って「my_custom_app_alias」というエイリアスを設定しています。その後、このエイリアスを利用したスタブと、Phar::running()で現在のエイリアスを表示するスクリプトをアーカイブ内に追加しています。これにより、作成されたPharファイルを実行した際に、設定したエイリアスが正しく認識され表示されることを確認できます。Pharアーカイブの書き込みには、PHPの設定でphar.readonlyが「Off」になっている必要があります。