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

Copy
1<?php
2
3// Phar拡張が有効になっていることを確認
4if (!extension_loaded('phar')) {
5    die('Phar拡張がロードされていません。php.iniを確認してください。');
6}
7
8// 一時的なPharファイル名とパスを定義
9$pharFileName = 'my_application.phar';
10$pharFilePath = __DIR__ . '/' . $pharFileName;
11
12// 既存のPharファイルがあれば削除（スクリプトを複数回実行するためのクリーンアップ）
13if (file_exists($pharFilePath)) {
14    unlink($pharFilePath);
15}
16
17try {
18    // 新しいPharアーカイブを作成します。
19    // 第1引数: 作成するPharファイルのパス
20    // 第2引数: フラグ (0でデフォルト)
21    // 第3引数: Pharアーカイブ名 (この名前でアーカイブ内のファイルが参照されます)
22    $phar = new Phar($pharFilePath, 0, $pharFileName);
23
24    // Pharアーカイブへの書き込みを開始（バッファリング）
25    $phar->startBuffering();
26
27    // アーカイブ内に含めるPHPファイルを文字列として追加
28    $phar->addFromString('cli_app.php', '<?php echo "CLIアプリケーションのロジックが実行されました。\n";');
29    $phar->addFromString('web_app.php', '<?php echo "Webアプリケーションのロジックが実行されました。\n";');
30
31    // CLI実行時に使用するカスタムスタブコードを定義
32    // このコードは、Pharファイルがコマンドラインから実行されたときに最初に実行されます。
33    // 'phar://' . __FILE__ . '/cli_app.php' でアーカイブ内のファイルを参照します。
34    // __HALT_COMPILER(); は、スタブの終わりとアーカイブデータの始まりを示します。
35    $cliStubCode = <<<'CLI_STUB'
36<?php
37echo "--- CLIスタブから実行中 ---\n";
38require 'phar://' . __FILE__ . '/cli_app.php';
39echo "--- CLIスタブ処理完了 ---\n";
40__HALT_COMPILER();
41CLI_STUB;
42
43    // Webサーバー経由でアクセスされた時に使用するカスタムスタブコードを定義
44    // このコードは、PharファイルがWebサーバーから実行されたときに最初に実行されます。
45    $webStubCode = <<<'WEB_STUB'
46<?php
47echo "--- Webスタブから実行中 ---\n";
48require 'phar://' . __FILE__ . '/web_app.php';
49echo "--- Webスタブ処理完了 ---\n";
50__HALT_COMPILER();
51WEB_STUB;
52
53    // Phar::setDefaultStub メソッドを使用して、CLI用とWeb用のデフォルトスタブを設定します。
54    // これにより、Pharファイルが直接実行されたときのエントリポイントを制御できます。
55    // 引数に `null` を渡した場合、Pharのデフォルトスタブが使用されます。
56    $phar->setDefaultStub($cliStubCode, $webStubCode);
57
58    // バッファリングを停止し、Pharファイルを書き込み、読み取り専用にします。
59    $phar->stopBuffering();
60
61    echo "Pharアーカイブ '{$pharFileName}' が正常に作成されました。\n";
62    echo "このPharファイルは、CLI実行とWeb実行で異なるスタブを持っています。\n";
63    echo "実行例:\n";
64    echo "  CLI: php {$pharFilePath}\n";
65    echo "  Web: (WebサーバーでPharファイルを直接配置してアクセス)\n";
66
67} catch (PharException $e) {
68    echo "Pharアーカイブの作成中にエラーが発生しました: " . $e->getMessage() . "\n";
69} catch (Exception $e) {
70    echo "予期せぬエラーが発生しました: " . $e->getMessage() . "\n";
71}

PHPのPhar::setDefaultStubメソッドは、PHPアプリケーションを単一ファイルにパッケージ化したPharアーカイブが実行された際、最初にどのようなコードを実行するか（スタブ）を設定するために使用されます。

このメソッドは、Pharファイルがコマンドライン（CLI）から実行される場合と、Webサーバー経由でアクセスされる場合とで、異なる起動処理を定義できる点が特徴です。

第1引数 $index には、CLIから実行されたときに処理されるスタブコードを文字列として指定します。第2引数 $webIndex には、Webサーバーからアクセスされたときに処理されるスタブコードを文字列として指定します。どちらの引数も null を指定した場合、Pharのデフォルトのスタブが使用されます。このメソッドに特定のコードを設定することで、アプリケーションの実行環境に応じて振る舞いを切り替えたり、異なるエントリポイントを設けたりすることが可能になります。戻り値は特にありません。

サンプルコードでは、CLI用とWeb用のスタブコードをそれぞれ定義し、setDefaultStubに渡して設定することで、実行環境に応じた異なるメッセージが表示されるようにしています。これにより、単一のPharファイルで複数の実行シナリオに対応できます。

Copy
1<?php
2
3// 一時的なPharアーカイブのファイル名を定義します。
4$pharFileName = 'my_application.phar';
5$pharFilePath = __DIR__ . '/' . $pharFileName;
6
7// 既存のPharファイルが存在する場合は削除し、常に新しいものを作成します。
8if (file_exists($pharFilePath)) {
9    unlink($pharFilePath);
10}
11
12try {
13    // 新しいPharアーカイブを作成します。
14    // コンストラクタの引数にファイルパスを指定します。ファイルが存在しない場合は新規作成されます。
15    $phar = new Phar($pharFilePath);
16
17    // Pharアーカイブの内容を編集するためにバッファリングを開始します。
18    // これにより、複数の変更をまとめてアーカイブに書き込むことができます。
19    $phar->startBuffering();
20
21    // アーカイブ内に 'index.php' ファイルを追加します。
22    // Pharの内部デフォルトスタブは、通常 'index.php' をエントリポイントとして探します。
23    $phar->addFromString('index.php', <<<'EOT'
24<?php
25// このコードは、PharアーカイブがPHPインタープリターで直接実行されたときに実行されます。
26echo "Hello from 'index.php' inside the Phar archive!\n";
27EOT
28    );
29
30    // Pharアーカイブのデフォルトスタブを設定します。
31    // setDefaultStub(null, null) を呼び出すと、Pharクラスが提供する内部のデフォルトスタブが使用されます。
32    // この内部デフォルトスタブは、PharアーカイブがCLIから実行された場合に 'index.php' を自動的に実行しようとします。
33    // 第1引数はCLI用のスタブ、第2引数はWebアクセス用のスタブですが、nullを指定するとPharの標準動作になります。
34    $phar->setDefaultStub(null, null);
35
36    // Pharファイルの変更を保存し、アーカイブを閉じます。
37    $phar->stopBuffering();
38
39    echo "Pharアーカイブ '{$pharFileName}' が正常に作成されました。\n";
40    echo "このアーカイブには 'index.php' が含まれており、デフォルトスタブはPharの内部ロジック（'index.php'を実行）を使用するように設定されています。\n\n";
41    echo "このPharアーカイブを実行するには、コマンドラインで以下のように入力してください:\n";
42    echo "php {$pharFileName}\n\n";
43    echo "期待される出力: \"Hello from 'index.php' inside the Phar archive!\"\n";
44
45} catch (PharException $e) {
46    // Phar関連のエラーを捕捉します。
47    echo "Pharアーカイブ作成中にエラーが発生しました: " . $e->getMessage() . "\n";
48} finally {
49    // サンプル実行後、Pharファイルを自動的に削除したい場合は、以下の行のコメントを解除してください。
50    // if (file_exists($pharFilePath)) {
51    //     unlink($pharFilePath);
52    //     echo "Pharアーカイブ '{$pharFileName}' を削除しました。\n";
53    // }
54}

Phar::setDefaultStubメソッドは、PHPのPhar（PHP Archive）ファイルが実行された際に、最初にどのコードを実行するか（エントリポイント）を設定するために使用されます。Pharファイルは、複数のPHPファイルやリソースを単一のアーカイブにまとめることで、アプリケーションの配布を容易にする仕組みです。

このメソッドには二つの引数があります。一つ目の$indexは、コマンドライン（CLI）からPharファイルが実行された際のエントリポイントを文字列で指定します。二つ目の$webIndexは、Webサーバー経由でPharファイルにアクセスされた場合のエントリポイントを文字列で指定します。どちらの引数もnullを指定した場合、Pharクラスが提供する標準の内部デフォルトスタブが使用されます。この内部スタブは、通常アーカイブ内のindex.phpファイルを自動的に実行しようとします。メソッドの戻り値はありません。

サンプルコードでは、my_application.pharというPharアーカイブを作成し、その中にindex.phpファイルを追加しています。そして、$phar->setDefaultStub(null, null);と設定することで、このPharアーカイブが実行された際に、内部のデフォルトロジックに従って追加されたindex.phpが自動的に実行されるように設定しています。これにより、php my_application.pharとコマンドを実行すると、アーカイブ内のindex.phpに書かれた「Hello from 'index.php' inside the Phar archive!」というメッセージが表示されます。この機能により、配布されたPharファイルが期待通りに動作するよう設定できるのです。