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

Copy
1<?php
2
3/**
4 * このスクリプトは、PHPのPharData::webPharメソッドの使用方法を示します。
5 * webPharメソッドは、Pharアーカイブをウェブサーバー経由で利用する際に、
6 * デフォルトのインデックスファイルやファイルが見つからない場合（404エラー）に
7 * どのスクリプトを実行するかなどを設定するために使われます。
8 */
9
10// Pharアーカイブを作成・変更するためには、php.iniで 'phar.readonly = 0' を設定するか、
11// 開発用途でのみ 'ini_set' を使用する必要があります。
12// 本番環境ではこの設定は推奨されません。
13if (ini_get('phar.readonly') == 1) {
14    echo "エラー: Pharアーカイブを作成するには 'phar.readonly' を '0' に設定する必要があります。\n";
15    echo "スクリプトを実行する前に php.ini を確認するか、開発環境で 'ini_set(\"phar.readonly\", 0);' を試してください。\n";
16    exit(1);
17}
18
19// 生成するPharアーカイブのファイル名
20$pharFileName = 'my_web_app.tar'; 
21// アーカイブに含めるファイルを一時的に配置するディレクトリ
22$tempDir = __DIR__ . '/temp_web_app_files'; 
23
24// 以前に作成されたPharアーカイブが存在する場合は削除し、クリーンな状態から始める
25if (file_exists($pharFileName)) {
26    unlink($pharFileName);
27}
28
29// 一時ディレクトリを作成し、Webアプリケーション用のサンプルファイルを追加
30if (!is_dir($tempDir)) {
31    mkdir($tempDir);
32}
33
34// index.php: デフォルトで表示されるページ
35file_put_contents($tempDir . '/index.php', '<?php echo "<h1>Hello from the Phar web app!</h1><p>This is the index page.</p>"; ?>');
36// about.php: 別のページ
37file_put_contents($tempDir . '/about.php', '<?php echo "<h1>About Us</h1><p>This is information about our app.</p>"; ?>');
38// 404.php: ファイルが見つからない場合に表示されるページ
39file_put_contents($tempDir . '/404.php', '<?php http_response_code(404); echo "<h1>404 Not Found</h1><p>The requested page could not be found.</p>"; ?>');
40// style.css: 静的ファイルも追加可能
41file_put_contents($tempDir . '/style.css', 'body { font-family: sans-serif; background-color: #f0f0f0; margin: 20px; } h1 { color: #333; }');
42
43try {
44    // 新しいPharDataアーカイブを作成
45    // PharDataは、Phar形式以外のアーカイブ（例: .tar、.zip）を操作するためのクラスです。
46    // .tarなどの形式でもwebPharメソッドを使用してウェブサーバーでの動作を設定できます。
47    $phar = new PharData($pharFileName);
48
49    // アーカイブ内のファイル圧縮を無効にする（オプション、tarは通常圧縮しない）
50    $phar->compress(Phar::NONE);
51
52    // 一時ディレクトリ内のすべてのファイルをPharアーカイブに追加
53    $phar->buildFromDirectory($tempDir);
54
55    // webPharメソッドを呼び出して、ウェブサーバーでのPharの動作を設定します。
56    // 第1引数: エイリアス (ウェブサーバーがPharを認識する名前、NULLの場合はファイル名を使用)
57    // 第2引数: インデックスファイル (リクエストがルートURL "/" の場合に実行されるファイル)
58    // 第3引数: ファイルが見つからない場合に実行されるスクリプト (404エラーページなど)
59    // その他の引数 (mimeTypes, rewrite) はオプションで、ここではデフォルトを使用します。
60    $phar->webPhar(
61        null,        // エイリアスは指定しない（ファイル名 my_web_app.tar が使用される）
62        'index.php', // ウェブサーバーからのリクエストのデフォルトファイル
63        '404.php'    // リクエストされたファイルが見つからない場合に実行されるスクリプト
64    );
65
66    echo "Pharアーカイブ '{$pharFileName}' が正常に作成され、webPhar設定が適用されました。\n";
67    echo "このPharアーカイブをウェブサーバー経由で利用する場合：\n";
68    echo "  - デフォルトのリクエスト（例: /）は 'index.php' にルーティングされます。\n";
69    echo "  - 存在しないファイルへのリクエストは '404.php' にルーティングされます。\n";
70    echo "  - PHPのビルトインサーバーでテストする場合、'php -S localhost:8000 {$pharFileName}' のように実行できます。\n";
71    echo "    ただし、これはPharを直接実行するものであり、webPharのフル機能を利用するには、\n";
72    echo "    Webサーバー（Apache/Nginx）の設定やphp.iniの 'auto_prepend_file' 設定が必要になる場合があります。\n";
73
74} catch (Exception $e) {
75    echo "Phar操作中にエラーが発生しました: " . $e->getMessage() . "\n";
76} finally {
77    // クリーンアップ: 作成した一時ディレクトリとその中のファイルを削除
78    if (is_dir($tempDir)) {
79        // ディレクトリ内のファイルを削除
80        foreach (glob("$tempDir/*") as $file) {
81            unlink($file);
82        }
83        // ディレクトリ自体を削除
84        rmdir($tempDir);
85    }
86}
87
88?>

PHP 8のPharData::webPharメソッドは、Phar形式のアーカイブ（複数のファイルを一つにまとめたもの）をウェブサーバー経由で利用する際に、ウェブアプリケーションとしての動作を設定するために使用されます。このメソッドにより、アーカイブ内のどのファイルをデフォルトのインデックスページとして表示するかや、存在しないページにアクセスされたときにどのスクリプトを実行するか（いわゆる404エラーページなど）を定義できます。

サンプルコードでは、my_web_app.tarというPharDataアーカイブを作成し、webPharメソッドでそのウェブ動作を設定しています。引数$aliasをNULLにするとアーカイブのファイル名がウェブサーバーに認識され、$indexに'index.php'を指定することで、ウェブサーバーへのデフォルトのリクエストがindex.phpにルーティングされます。また、$fileNotFoundScriptに'404.php'を設定することで、存在しないファイルへのリクエストが404.phpで処理されるようになります。

このメソッドには戻り値がなく、PharDataアーカイブにウェブPharとしての振る舞いを設定する役割を果たします。ウェブサーバーでPharアーカイブをWebアプリケーションとして機能させるには、php.iniでphar.readonlyを0に設定する必要があります。

Copy
1<?php
2
3// Pharアーカイブの書き込みを一時的に許可する設定。
4// この設定は開発環境やテストでのみ推奨されます。
5// 本番環境ではセキュリティ上の理由から `phar.readonly` を `On` に保つことが一般的です。
6ini_set('phar.readonly', 'Off');
7
8/**
9 * Web APIとして動作するPharDataアーカイブを作成し、Webアクセス設定を行う。
10 *
11 * この関数は、システムエンジニアを目指す初心者向けに、
12 * PHPのPharDataアーカイブを単一のファイルとしてWebアプリケーションのように
13 * デプロイし、Web APIとして機能させるための基本的な設定方法を示します。
14 *
15 * 関数が実行されると、スクリプトが配置されているディレクトリに
16 * 'my_web_api.tar' という名前のPharDataアーカイブファイルが生成されます。
17 * このアーカイブをWebサーバーのドキュメントルートに配置することで、
18 * 定義されたWeb APIエンドポイントにアクセスできるようになります。
19 */
20function createAndConfigureWebApiPharData(): void
21{
22    $pharFileName = 'my_web_api.tar'; // 生成するPharDataアーカイブの名前
23    $pharFilePath = __DIR__ . '/' . $pharFileName;
24
25    // 既存のPharDataアーカイブがあれば削除し、クリーンな状態で開始する。
26    if (file_exists($pharFilePath)) {
27        unlink($pharFilePath);
28    }
29
30    try {
31        // 新しいPharDataアーカイブを作成。
32        // このアーカイブがWeb APIのすべてのコンテンツを格納するコンテナとなります。
33        $phar = new PharData($pharFilePath);
34
35        // PharDataアーカイブにWeb APIのファイルを模擬的に追加する。
36        // これらのファイルは、Webサーバー経由でアーカイブがアクセスされたときに実行されます。
37
38        // index.php: Web APIのデフォルトエントリポイント。
39        // GETパラメータ 'action=status' に応答する例。
40        $phar->addFromString('index.php', <<<'EOT'
41<?php
42header('Content-Type: application/json');
43if (isset($_GET['action']) && $_GET['action'] === 'status') {
44    echo json_encode(['status' => 'ok', 'message' => 'API is running']);
45} else {
46    http_response_code(400); // Bad Request
47    echo json_encode(['status' => 'error', 'message' => 'Invalid or missing action parameter']);
48}
49EOT
50        );
51
52        // api/v1/user.php: ユーザー情報に関するAPIエンドポイントの例。
53        // 固定のユーザーデータをJSON形式で返します。
54        $phar->addFromString('api/v1/user.php', <<<'EOT'
55<?php
56header('Content-Type: application/json');
57echo json_encode(['id' => 1, 'name' => 'John Doe', 'email' => 'john.doe@example.com']);
58EOT
59        );
60
61        // 404.php: リクエストされたリソースがアーカイブ内で見つからなかった場合に実行されるスクリプト。
62        $phar->addFromString('404.php', <<<'EOT'
63<?php
64header('Content-Type: application/json');
65http_response_code(404);
66echo json_encode(['status' => 'error', 'message' => 'Resource not found in PharData archive']);
67EOT
68        );
69
70        // PharDataアーカイブがWebサーバーでアクセスされた際の挙動を設定。
71        // webPharメソッドは、URLリクエストをアーカイブ内のどのファイルにマッピングするかを定義します。
72        $phar->webPhar(
73            null,                       // $alias: NULLの場合、アーカイブ名 (my_web_api.tar) がエイリアスとして使用されます。
74            'index.php',                // $index: デフォルトのインデックスファイル。URLにファイル名がない場合に実行されます。
75            '404.php',                  // $fileNotFoundScript: リクエストされたファイルが見つからない場合に実行されるスクリプト。
76            [                           // $mimeTypes: 特定のファイル拡張子に対するMIMEタイプを設定します。
77                'json' => 'application/json',
78                'php' => 'application/x-httpd-php', // PHPファイルはPHPインタープリタで処理されるように指定。
79            ],
80            function (string $url, int $errorCode, array $metadata): ?string {
81                // $rewrite: URL書き換えロジックを定義するコールバック関数です。
82                // このコールバックを使用して、外部からのURLをPharDataアーカイブ内部の
83                // どのファイルにマッピングするかをカスタマイズできます。
84                //
85                // 例: `/api/v1/users` のような「きれいなURL」リクエストを、
86                //     アーカイブ内部の `api/v1/user.php` にルーティングします。
87                if (preg_match('/^\/api\/v1\/users(\/.*)?$/', $url)) {
88                    return 'api/v1/user.php';
89                }
90                // null を返すと、WebPharのデフォルトのファイルマッピングロジックが継続されます。
91                return null;
92            }
93        );
94
95    } catch (Throwable $e) {
96        // 例外が発生した場合、エラーはログに記録される可能性がありますが、
97        // サンプルコード以外の出力を避けるため、ここでは何も表示しません。
98        // error_log("Error creating or configuring PharData: " . $e->getMessage());
99    } finally {
100        // このPharDataファイルはWebサーバーで利用されることを想定しているため、
101        // 関数終了時に削除せず、永続化させます。
102    }
103}
104
105// 関数を実行し、PharDataアーカイブを作成してWebPhar設定を適用する。
106createAndConfigureWebApiPharData();
107
108// スクリプトの終了時に `phar.readonly` 設定は自動的に元の値に戻ります。

このPHPコードは、PharData::webPharメソッドを利用して、単一ファイルでWeb APIとして機能するPharDataアーカイブを作成し、そのWebアクセス設定を行う方法を示しています。PharData::webPharメソッドは戻り値を提供しませんが、Webサーバーからアーカイブがアクセスされた際の振る舞いを定義するために使用されます。

サンプルコードでは、まずmy_web_api.tarというPharDataアーカイブを生成し、Web APIのメインエントリポイントとなるindex.phpや特定のエンドポイントを模したapi/v1/user.php、ファイルが見つからない場合に表示する404.phpといったスクリプトをアーカイブ内部に格納しています。

その後、webPharメソッドを呼び出し、引数$aliasでアーカイブのWeb上での名前（ここではアーカイブ名が使用されます）、$indexでURLにファイル名がない場合に実行されるデフォルトのファイル（index.php）、$fileNotFoundScriptでリクエストされたファイルが見つからなかった場合に実行されるスクリプト（404.php）を設定しています。さらに、$mimeTypes引数でJSONやPHPファイルのContent-Typeを定義し、$rewrite引数にはコールバック関数を渡して、/api/v1/usersのような「きれいなURL」をアーカイブ内部のapi/v1/user.phpに紐付けるルーティングルールを実装しています。

これにより、生成されたmy_web_api.tarファイルをWebサーバーのドキュメントルートに配置するだけで、この単一ファイルがWeb APIとして動作するようになります。コード冒頭のini_set('phar.readonly', 'Off')は、アーカイブの書き込みを一時的に許可するための開発環境向け設定であり、本番環境では注意が必要です。