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

Copy
1<?php
2
3/**
4 * PharFileInfo::isWritable メソッドの基本的な使用例を示す関数。
5 *
6 * この関数は以下の手順で動作します：
7 * 1. 一時的なPhar (PHP Archive) ファイルを作成し、内部にテストファイルを格納します。
8 * 2. 作成したPharファイルから、格納したテストファイルの情報を取得します (PharFileInfo)。
9 * 3. PharFileInfo::isWritable メソッドを使用して、そのテストファイルが書き込み可能かどうかをチェックします。
10 * 4. 結果を表示し、最後に一時ファイルとして作成したPharファイルを削除します。
11 *
12 * システムエンジニアを目指す初心者の方へ:
13 * Pharは、複数のPHPファイルを一つのアーカイブにまとめて配布するための仕組みです。
14 * 通常、Pharアーカイブ内のファイルはアプリケーションの実行時に変更されることは想定されていません。
15 * そのため、PharFileInfo::isWritable メソッドが 'false' を返すことが一般的です。
16 *
17 * 注意: Pharアーカイブを作成するには、php.ini で 'phar.readonly=Off' が設定されている必要があります。
18 * コマンドラインから実行する場合、`php -d phar.readonly=0 your_script.php` のように指定できます。
19 */
20function demonstratePharFileIsWritable(): void
21{
22    // 一時的に作成するPharアーカイブのファイルパス
23    // __DIR__ は現在のスクリプトがあるディレクトリを示します。
24    $temporaryPharPath = __DIR__ . '/example_archive.phar';
25    // アーカイブ内に格納するファイルの論理名（アーカイブ内でのパス）
26    $internalFileName = 'my_application/config.ini';
27    // アーカイブ内に格納するファイルの内容
28    $fileContent = '[Settings]' . PHP_EOL . 'debug = true';
29
30    echo "--- PharFileInfo::isWritable のデモンストレーションを開始 ---" . PHP_EOL;
31
32    try {
33        // 古いPharアーカイブが存在する場合、削除してクリーンな状態から開始します。
34        if (file_exists($temporaryPharPath)) {
35            unlink($temporaryPharPath);
36            echo "INFO: 既存のPharアーカイブ '{$temporaryPharPath}' を削除しました。" . PHP_EOL;
37        }
38
39        // 1. 新しいPharアーカイブを作成（書き込みモード）
40        // Pharオブジェクトを新規にインスタンス化します。
41        // この操作には、PHPの設定 'phar.readonly' が 'Off' である必要があります。
42        $phar = new Phar($temporaryPharPath);
43
44        // アーカイブへのファイル追加処理をバッファリングし、効率化します。
45        $phar->startBuffering();
46
47        // 指定した内容の文字列をファイルとしてアーカイブに追加します。
48        $phar->addFromString($internalFileName, $fileContent);
49
50        // バッファリングを終了し、Pharアーカイブをディスクに書き込み保存します。
51        // この時点で、Pharアーカイブは通常「読み取り専用」の状態になります。
52        $phar->stopBuffering();
53
54        echo "INFO: Pharアーカイブ '{$temporaryPharPath}' が正常に作成されました。" . PHP_EOL;
55        echo "INFO: 内部ファイル '{$internalFileName}' がアーカイブに追加されました。" . PHP_EOL;
56
57        // 2. 作成したPharアーカイブから特定のファイル情報を取得
58        // Pharオブジェクトから、アーカイブ内の 'my_application/config.ini' ファイルのエントリを取得します。
59        // このエントリは PharFileInfo のインスタンスです。
60        $pharFileInfo = $phar->offsetGet($internalFileName);
61
62        // 取得したオブジェクトが期待通り PharFileInfo のインスタンスであることを確認します。
63        if ($pharFileInfo instanceof PharFileInfo) {
64            // 3. PharFileInfo::isWritable メソッドの呼び出し
65            // このメソッドは、Pharアーカイブ内の指定されたファイルが書き込み可能かどうかをチェックし、
66            // その結果をブール値 (true または false) で返します。
67            $isWritable = $pharFileInfo->isWritable();
68
69            // 4. 結果の表示
70            if ($isWritable) {
71                echo "RESULT: Pharアーカイブ内のファイル '{$internalFileName}' は書き込み可能です。" . PHP_EOL;
72                echo "補足: この状況は非常に稀です。Pharファイルは通常、作成後に変更されることは想定されていません。" . PHP_EOL;
73            } else {
74                echo "RESULT: Pharアーカイブ内のファイル '{$internalFileName}' は書き込み不可能です。" . PHP_EOL;
75                echo "補足: これはPharアーカイブの一般的な動作であり、想定される結果です。" . PHP_EOL;
76            }
77        } else {
78            echo "ERROR: Pharアーカイブから '{$internalFileName}' のPharFileInfoオブジェクトを取得できませんでした。" . PHP_EOL;
79        }
80
81    } catch (PharException $e) {
82        // Phar関連の操作で発生するエラーをキャッチします。
83        // 例: 'phar.readonly=On' の設定でPharの書き込みを試みた場合など。
84        echo "ERROR: Phar操作中にエラーが発生しました: " . $e->getMessage() . PHP_EOL;
85        echo "ヒント: Pharアーカイブを作成するには、php.iniで 'phar.readonly=Off' を設定するか、" . PHP_EOL;
86        echo "       コマンドラインで `php -d phar.readonly=0 your_script.php` のように実行してください。" . PHP_EOL;
87    } catch (Exception $e) {
88        // その他の予期せぬエラーをキャッチします。
89        echo "ERROR: 予期せぬエラーが発生しました: " . $e->getMessage() . PHP_EOL;
90    } finally {
91        // 最終処理: スクリプトの終了時に、作成した一時Pharアーカイブファイルを削除してクリーンアップします。
92        if (file_exists($temporaryPharPath)) {
93            unlink($temporaryPharPath);
94            echo "INFO: 一時Pharアーカイブ '{$temporaryPharPath}' を削除しました。" . PHP_EOL;
95        }
96    }
97
98    echo "--- デモンストレーション終了 ---" . PHP_EOL;
99}
100
101// 上記で定義した関数を実行し、PharFileInfo::isWritable の動作を示します。
102demonstratePharFileIsWritable();

PharFileInfo::isWritableメソッドは、PHPのPhar（PHP Archive）拡張機能に属し、Pharアーカイブ内に格納されている特定のファイルが書き込み可能かどうかを判定するために使用されます。このメソッドは引数を一切受け取らず、判定結果を真偽値（trueまたはfalse）として返します。

このサンプルコードでは、まず一時的なPharアーカイブファイルを作成し、その内部にテスト用の設定ファイルを追加しています。その後、作成されたPharアーカイブから、追加したテストファイルの情報をPharFileInfoオブジェクトとして取得します。このPharFileInfoオブジェクトに対してisWritableメソッドを呼び出すことで、アーカイブ内のそのファイルが書き込み可能であるかを確認し、その結果を表示しています。

Pharアーカイブは通常、アプリケーションの配布やデプロイを目的としたものであり、一度作成されると内部のファイルは読み取り専用として扱われることが一般的です。そのため、isWritableメソッドはfalseを返すケースがほとんどであり、これは想定される挙動です。Pharアーカイブを作成する際には、PHPの設定ファイル（php.ini）でphar.readonly=Offが設定されている必要があります。このメソッドは、アーカイブ内のファイルの変更可能性をプログラムで確認する際に役立ちます。

Copy
1<?php
2
3// 環境設定チェック: PHARアーカイブの作成には 'phar.readonly' を '0' に設定する必要があります。
4// CLI (コマンドライン) 環境で実行する場合、以下のように指定してください:
5// php -d phar.readonly=0 your_script_name.php
6if (ini_get('phar.readonly') == '1') {
7    echo "エラー: PHPの設定 'phar.readonly' が '1' に設定されています。\n";
8    echo "このスクリプトを実行するには、'phar.readonly' を '0' に変更する必要があります。\n";
9    echo "例: php -d phar.readonly=0 " . basename(__FILE__) . "\n";
10    exit(1);
11}
12
13// 一時的なディレクトリとPHARファイル名を定義します。
14$tmpDir = __DIR__ . '/phar_temp_example';
15$pharFileName = $tmpDir . '/example_archive.phar';
16$innerFileName = 'content.txt';
17$innerFilePath = $tmpDir . '/' . $innerFileName;
18
19/**
20 * サンプル実行後に生成された一時ファイルをクリーンアップする関数です。
21 *
22 * @param string $tmpDir 一時ディレクトリのパス
23 * @param string $pharFileName 生成されたPHARアーカイブファイルのパス
24 * @param string $innerFilePath PHARに含められた内部ファイルのパス
25 */
26function cleanup(string $tmpDir, string $pharFileName, string $innerFilePath): void
27{
28    // PHARに含めた一時ファイルを削除します。
29    if (file_exists($innerFilePath)) {
30        unlink($innerFilePath);
31    }
32    // 生成されたPHARアーカイブファイルを削除します。
33    // Phar::unlinkArchive() は、PHAR関連のファイルを安全に削除するための推奨メソッドです。
34    if (file_exists($pharFileName)) {
35        Phar::unlinkArchive($pharFileName);
36    }
37    // 一時ディレクトリを削除します。
38    if (is_dir($tmpDir)) {
39        rmdir($tmpDir);
40    }
41}
42
43// スクリプト開始前に、前回の実行で残された可能性のあるファイルをクリーンアップします。
44cleanup($tmpDir, $pharFileName, $innerFilePath);
45
46// PHARアーカイブを生成するための一時ディレクトリを作成します。
47if (!mkdir($tmpDir, 0777, true) && !is_dir($tmpDir)) {
48    throw new RuntimeException(sprintf('一時ディレクトリ "%s" の作成に失敗しました。', $tmpDir));
49}
50
51// PHARアーカイブに格納するダミーファイルを作成します。
52file_put_contents($innerFilePath, 'これはPHARアーカイブに格納されるテストコンテンツです。');
53
54try {
55    echo "--- PharFileInfo::isWritable() メソッドの動作確認 --- \n\n";
56
57    // 1. 新しいPHARアーカイブを「書き込みモード」で作成開始します。
58    // 引数: (PHARファイルパス, フラグ, PHAR内部で参照される名前)
59    $phar = new Phar($pharFileName, 0, 'example_archive.phar');
60    $phar->startBuffering(); // PHARへの変更を一時的にメモリに保持し始めます。
61    $phar->addFile($innerFilePath, $innerFileName); // ダミーファイルをPHARアーカイブに追加します。
62    $phar->setDefaultStub(); // PHARを実行可能なスクリプトとして機能させるためのスタブを設定します。
63
64    echo "PHARアーカイブが「書き込みモード」で開かれている状態です。\n";
65    // PharFileInfo::isWritable() を呼び出し、アーカイブ内のファイルの書き込み可能性をチェックします。
66    // この時点では、PHARオブジェクトが書き込み用に開かれているため、通常は 'true' (はい) を返します。
67    $pharFileInfoDuringWrite = $phar[$innerFileName];
68    echo "  ファイル '{$innerFileName}' は書き込み可能ですか？: ";
69    echo $pharFileInfoDuringWrite->isWritable() ? "はい\n" : "いいえ\n";
70
71    $phar->stopBuffering(); // バッファリングを終了し、変更をPHARファイルに書き込みます。
72    // ここでPHARアーカイブは閉じられ、ディスクに保存され、通常は読み取り専用となります。
73    echo "\nPHARアーカイブがディスクに保存され、最終化されました。\n\n";
74
75    // 2. 作成されたPHARアーカイブを「読み込み専用モード」で開きます。
76    // (一度作成されたPHARアーカイブは、通常、自動的に読み込み専用として開かれます)
77    // `$phar = null;` のように参照を解除すると、PHARファイルをより確実に解放できます。
78    unset($phar); 
79    $pharReadonly = new Phar($pharFileName);
80
81    echo "PHARアーカイブが「読み込み専用モード」で開かれている状態です (作成後)。\n";
82    // PharFileInfo::isWritable() を再度呼び出し、結果をチェックします。
83    // この時点では、PHARアーカイブが読み込み専用であるため、通常は 'false' (いいえ) を返します。
84    $pharFileInfoAfterCreation = $pharReadonly[$innerFileName];
85    echo "  ファイル '{$innerFileName}' は書き込み可能ですか？: ";
86    echo $pharFileInfoAfterCreation->isWritable() ? "はい\n" : "いいえ\n";
87
88} catch (PharException $e) {
89    // PHAR関連の操作でエラーが発生した場合の処理
90    echo "エラー: PHAR操作中に問題が発生しました: " . $e->getMessage() . "\n";
91    exit(1);
92} catch (RuntimeException $e) {
93    // その他の予期せぬエラーが発生した場合の処理
94    echo "エラー: スクリプト実行中に予期せぬ問題が発生しました: " . $e->getMessage() . "\n";
95    exit(1);
96} finally {
97    // スクリプト終了時に、生成された一時ファイルをクリーンアップします。
98    // `$pharReadonly = null;` のように参照を解除すると、ファイルをより確実に解放できます。
99    unset($pharReadonly); 
100    cleanup($tmpDir, $pharFileName, $innerFilePath);
101    echo "\nクリーンアップが完了しました。\n";
102}
103
104?>

PharFileInfo::isWritable()メソッドは、PHPのPHARアーカイブ（複数のファイルを一つにまとめた形式）内に含まれる個々のファイルやディレクトリが、現在書き込み可能かどうかを判断するために使用されます。このメソッドは引数を必要とせず、書き込み可能であればtrueを、書き込み不可能であればfalseという真偽値を戻り値として返します。

サンプルコードでは、まずPHARアーカイブを新しく作成し、ファイルをアーカイブに追加する「書き込みモード」の状態でisWritable()を呼び出しています。この時点では、まだアーカイブの内容が確定しておらず、内部のファイルは書き込み可能な状態とみなされるため、メソッドはtrueを返します。

しかし、PHARアーカイブが完成してディスクに保存されると、通常は「読み込み専用モード」で開かれるようになります。この読み込み専用の状態で再びisWritable()を呼び出すと、アーカイブ内のファイルへの直接書き込みはできなくなるため、メソッドはfalseを返します。

このように、isWritable()はPHARアーカイブの現在のモード（書き込みモードか読み込み専用モードか）に応じて、内部ファイルの書き込み可否を正確に判断する役割を担っています。PHARアーカイブの作成や変更には、PHP設定のphar.readonlyが0に設定されている必要がある点も、運用上重要な要素です。