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

Copy
1<?php
2
3/**
4 * Creates a Phar archive with a default stub.
5 * This function demonstrates the use of Phar::createDefaultStub to
6 * generate a standard bootloader for a self-executable PHP archive.
7 *
8 * @param string $pharFileName The name of the Phar archive file to create.
9 */
10function createPharWithDefaultStub(string $pharFileName): void
11{
12    // Ensure 'phar.readonly' is set to 0 to allow Phar archive creation/modification.
13    // In a production environment, this setting should be configured in php.ini.
14    if (ini_get('phar.readonly') == 1) {
15        // Attempt to override the setting for the current script's execution.
16        ini_set('phar.readonly', 0);
17        if (ini_get('phar.readonly') == 1) {
18            echo "Error: Cannot create Phar archive. 'phar.readonly' must be set to 0.\n";
19            return;
20        }
21    }
22
23    $pharFilePath = __DIR__ . '/' . $pharFileName;
24
25    // Remove any existing Phar file to ensure a clean slate for the demonstration.
26    if (file_exists($pharFilePath)) {
27        unlink($pharFilePath);
28    }
29
30    try {
31        // Create a new Phar archive object.
32        $phar = new Phar($pharFilePath);
33
34        // Start buffering changes. This makes the creation process more efficient.
35        $phar->startBuffering();
36
37        // Add a simple 'index.php' file, executed when the Phar is run from CLI.
38        $phar->addFromString('index.php', '<?php echo "Hello from Phar (CLI)!\\n";');
39
40        // Add a 'web/index.php' file, executed when the Phar is accessed via a web server.
41        $phar->addFromString('web/index.php', '<?php echo "Hello from Phar (Web)!";');
42
43        // Generate a default stub string.
44        // This static method creates a standard PHP bootloader script.
45        // It provides a robust entry point for the Phar archive,
46        // making it executable from both command line and web server.
47        // The arguments specify the main script for CLI and web access within the Phar.
48        $defaultStub = Phar::createDefaultStub('index.php', 'web/index.php');
49
50        // Set the generated stub as the Phar's bootloader.
51        // This is the first script executed when the Phar archive is invoked.
52        $phar->setStub($defaultStub);
53
54        // Stop buffering and write all accumulated changes to the Phar file on disk.
55        $phar->stopBuffering();
56
57        echo "Successfully created Phar archive: '" . $pharFileName . "'.\n";
58        echo "You can test it from the command line: php " . escapeshellarg($pharFilePath) . "\n";
59        echo "Or access it via a web server if configured.\n";
60
61    } catch (PharException $e) {
62        // Catch specific Phar-related exceptions.
63        echo "Error creating Phar archive: " . $e->getMessage() . "\n";
64        // Attempt to clean up the partially created file if an error occurred.
65        if (file_exists($pharFilePath)) {
66            unlink($pharFilePath);
67        }
68    } catch (Exception $e) {
69        // Catch any other unexpected exceptions.
70        echo "An unexpected error occurred: " . $e->getMessage() . "\n";
71    }
72}
73
74// --- Script Execution ---
75$pharFileName = 'my_app_with_default_stub.phar';
76createPharWithDefaultStub($pharFileName);
77
78// Note: The created '.phar' file is left on disk for inspection.
79// You might want to manually delete it after testing.
80// For automated tests, you would typically add cleanup code here.

PHP 8のPhar::createDefaultStubメソッドは、自己実行可能なPHPアーカイブであるPharファイルの起動時に最初に実行される「スタブ」と呼ばれるコードを生成します。このスタブは、Pharファイルがコマンドライン（CLI）から実行された場合や、Webサーバー経由でアクセスされた場合のプログラムのエントリポイント（開始点）を定義する重要な役割を担っています。

引数として$indexにはコマンドライン実行時のメインスクリプトのファイル名を、$webIndexにはWebアクセス時のメインスクリプトのファイル名を指定します。これらの引数はどちらも省略可能（NULL指定）で、その場合はPharの標準的なデフォルト動作が適用されます。このメソッドは、生成されたスタブのPHPコードを含む文字列を戻り値として返します。

サンプルコードでは、まず新しいPharアーカイブを作成し、内部にindex.phpとweb/index.phpという2つのファイルを追加しています。その後にPhar::createDefaultStubを呼び出し、これら2つのファイルをそれぞれCLIとWebの起動スクリプトとして指定して、標準的なスタブコードを生成しています。生成されたスタブはPhar::setStub()メソッドによってPharアーカイブに設定され、最終的にPharファイルがコマンドラインやWebサーバーから実行可能なアプリケーションとして機能するようになります。

Copy
1<?php
2
3/**
4 * このスクリプトは、PHPのPhar拡張機能を使用して実行可能なアーカイブを作成し、
5 * そのアーカイブの起動コード（スタブ）を設定する例を示します。
6 *
7 * 注意: Pharアーカイブを作成するには、php.ini設定ファイルで `phar.readonly = Off`
8 * に設定するか、CLIから `php -d phar.readonly=0 your_script.php` のように
9 * オプションを指定して実行する必要があります。
10 */
11
12// 一時的なディレクトリとファイルを作成し、Pharアーカイブの準備をします。
13$tempDir = sys_get_temp_dir() . '/phar_example_' . uniqid('phar_');
14if (!mkdir($tempDir) && !is_dir($tempDir)) {
15    throw new RuntimeException(sprintf('Directory "%s" was not created', $tempDir));
16}
17
18// PHARアーカイブに含めるPHPファイルを作成します。
19// これがCLIからPHARを実行したときのデフォルトのエントリポイントになります。
20file_put_contents($tempDir . '/cli_app.php', <<<'EOT'
21<?php
22// cli_app.php - このファイルはCLIからPharが実行されたときに呼び出されます。
23echo "Hello from PHAR CLI Application!\n";
24echo "Received arguments: " . implode(', ', array_slice($argv, 1)) . "\n";
25EOT);
26
27// Webサーバー経由でPHARにアクセスされたときのデフォルトのエントリポイントファイルを作成します。
28file_put_contents($tempDir . '/web_app.php', <<<'EOT'
29<?php
30// web_app.php - このファイルはWebサーバー経由でPharがアクセスされたときに呼び出されます。
31echo "<h1>Hello from PHAR Web Application!</h1>\n";
32echo "<p>Request URI: " . htmlspecialchars($_SERVER['REQUEST_URI']) . "</p>\n";
33EOT);
34
35// PHARアーカイブの出力パスを設定します。
36$pharPath = $tempDir . '/my_application.phar';
37
38try {
39    // 1. 新しいPharアーカイブを書き込みモードで開きます。
40    $phar = new Phar($pharPath);
41    // バッファリングを開始し、Pharアーカイブへの変更を一時的にメモリに保持します。
42    $phar->startBuffering();
43
44    // 2. Pharアーカイブにファイルを追加します。
45    // 今回は一時ディレクトリ内のすべてのPHPファイルをアーカイブに含めます。
46    $phar->buildFromDirectory($tempDir, '/\.php$/');
47
48    // 3. Phar::createDefaultStub() を使用して、デフォルトの実行スタブを生成します。
49    // このスタブは、PHARファイルがPHPによって実行されたときに最初に処理されるコードです。
50    //
51    // 引数:
52    // - $index (string|null): CLIからPharが実行されたときにインクルードされるファイル名。
53    // - $webIndex (string|null): Webサーバー経由でPharがアクセスされたときにインクルードされるファイル名。
54    //   両方NULLの場合、デフォルトは 'index.php' またはアーカイブ内の最初のPHPファイルになります。
55    //
56    // 注意: キーワードの `phpunit createstub` は、単体テストの文脈でテスト用の
57    // スタブオブジェクトを生成するPHPUnitのメソッドであり、ここで扱うPharアーカイブの
58    // 実行可能スタブとは機能が全く異なります。このPhar::createDefaultStubは、
59    // Pharアーカイブのローダーコードを生成します。
60    $defaultStub = Phar::createDefaultStub('cli_app.php', 'web_app.php');
61
62    // 4. 生成したスタブをPharアーカイブに設定します。
63    $phar->setStub($defaultStub);
64
65    // 5. バッファリングを終了し、すべての変更をPharアーカイブファイルに書き込みます。
66    $phar->stopBuffering();
67
68    echo "Pharアーカイブが正常に作成されました: " . $pharPath . "\n";
69    echo "--------------------------------------------------------\n";
70    echo "Pharアーカイブの実行方法:\n";
71    echo "CLIから実行: php " . escapeshellarg($pharPath) . " first_arg second_arg\n";
72    echo "Webサーバー経由: (WebサーバーがPharファイルをPHPとして処理するように設定されている場合)\n";
73    echo " 例: http://localhost/my_application.phar\n";
74    echo "--------------------------------------------------------\n";
75
76} catch (PharException $e) {
77    echo "Pharアーカイブの作成中にエラーが発生しました: " . $e->getMessage() . "\n";
78} catch (Exception $e) {
79    echo "予期せぬエラーが発生しました: " . $e->getMessage() . "\n";
80} finally {
81    // クリーンアップ: 作成した一時ファイルとディレクトリを削除します。
82    // エラーが発生した場合でもクリーンアップを試みます。
83    if (file_exists($tempDir . '/cli_app.php')) {
84        unlink($tempDir . '/cli_app.php');
85    }
86    if (file_exists($tempDir . '/web_app.php')) {
87        unlink($tempDir . '/web_app.php');
88    }
89    if (file_exists($pharPath)) {
90        unlink($pharPath);
91    }
92    if (is_dir($tempDir)) {
93        rmdir($tempDir);
94    }
95    echo "一時ファイルとディレクトリがクリーンアップされました。\n";
96}
97
98?>

PHPのPhar::createDefaultStubメソッドは、複数のPHPファイルを一つにまとめたPharアーカイブファイルを作成する際に、そのアーカイブの起動コード（スタブ）を自動で生成するために利用されます。

このメソッドには二つのオプション引数があります。一つ目の$indexは、コマンドラインインターフェース（CLI）からPharアーカイブを実行したときに最初に処理されるファイル名を指定します。二つ目の$webIndexは、Webサーバー経由でPharアーカイブにアクセスした際に最初に処理されるファイル名を指定します。これらの引数を指定することで、CLIとWebのそれぞれで異なる開始点を設定できます。引数を省略したりNULLにしたりした場合は、アーカイブ内の適切なデフォルトファイルが自動的に選択されます。メソッドは、生成されたスタブのコードを文字列として返します。この文字列は、その後Phar::setStub()メソッドに渡して、Pharアーカイブの実際の起動コードとして設定します。

キーワードの「phpunit createstub」は、単体テストツールPHPUnitでテスト用のダミーオブジェクトを生成する機能であり、Phar::createDefaultStubとは機能も用途も全く異なりますので、混同しないように注意が必要です。Pharアーカイブを作成する際には、PHPの設定でphar.readonly = Offにする必要があります。