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

Copy
1<?php
2
3/**
4 * Pharアーカイブのファイル名が有効な形式であるかをチェックするサンプルコード。
5 *
6 * この関数は、PharData::isValidPharFilename メソッドを使用して、
7 * 与えられたファイル名がPharアーカイブとして妥当な形式であるかを判断します。
8 *
9 * PharData::isValidPharFilename はインスタンスメソッドであるため、
10 * PharDataのインスタンスを作成する必要があります。
11 * このメソッドはファイル名文字列の形式のみをチェックし、
12 * 実際にファイルが存在するかどうかや、その中身は確認しません。
13 * しかし、PharDataコンストラクタは有効なアーカイブファイルパスを要求するため、
14 * サンプルでは一時的なダミーファイルを指定し、インスタンスを生成します。
15 */
16function checkPharFilenameValidity(): void
17{
18    // isValidPharFilenameメソッドはインスタンスメソッドのため、PharDataインスタンスが必要です。
19    // このメソッドはファイル名文字列の形式のみをチェックし、
20    // インスタンスが参照する実際のアーカイブファイルの内容とは無関係です。
21    // ここでは、コンストラクタが成功するように一時的なダミーのアーカイブファイルを作成し、
22    // そのファイル名でPharDataインスタンスを生成します。
23    $dummyArchiveFile = 'temp_dummy_archive.tar';
24    $pharData = null; // PharDataインスタンスを初期化
25
26    try {
27        // PharDataコンストラクタは、指定されたファイルが存在しない場合でも
28        // Phar::CREATEフラグを使用すると新しいPharアーカイブを作成します。
29        // これにより、ファイルが存在しないことによるPharExceptionを回避しつつ、
30        // PharDataインスタンスを正常に生成できます。
31        // この操作はisValidPharFilenameのチェック自体には本質的に不要ですが、
32        // インスタンスメソッドの呼び出しのために必要となります。
33        $pharData = new PharData($dummyArchiveFile, Phar::CREATE);
34
35        // チェックするファイル名のリストと、期待される挙動の説明
36        $filenamesToCheck = [
37            'my_app.phar'      => ['executable' => true, 'description' => '標準的なPharアーカイブ'],
38            'my_app.phar.gz'   => ['executable' => true, 'description' => 'Gzip圧縮されたPharアーカイブ'],
39            'my_app.phar.bz2'  => ['executable' => true, 'description' => 'Bzip2圧縮されたPharアーカイブ'],
40            'archive.tar'      => ['executable' => false, 'description' => 'tarアーカイブ (非実行可能)'],
41            'archive.zip'      => ['executable' => false, 'description' => 'zipアーカイブ (非実行可能)'],
42            'another_app.phar' => ['executable' => false, 'description' => 'Pharアーカイブ (非実行可能)'],
43            'archive.tar.gz'   => ['executable' => false, 'description' => 'Gzip圧縮されたtarアーカイブ (非実行可能)'],
44            'my_script.php'    => ['executable' => true, 'description' => 'PHPスクリプト (無効)'],
45            'document.txt'     => ['executable' => true, 'description' => 'テキストファイル (無効)'],
46            'no_extension'     => ['executable' => true, 'description' => '拡張子なしファイル (無効)'],
47            'malicious.exe'    => ['executable' => true, 'description' => 'Windows実行ファイル (無効)'],
48        ];
49
50        echo "Pharアーカイブのファイル名妥当性チェック:\n";
51        echo "--------------------------------------\n";
52
53        foreach ($filenamesToCheck as $filename => $options) {
54            $isValid = $pharData->isValidPharFilename($filename, $options['executable']);
55            $executableContext = $options['executable'] ? '実行可能として' : '非実行可能として';
56            $result = $isValid ? '有効' : '無効';
57            echo sprintf(
58                "ファイル名 '%s' (%s): %s -> %s\n",
59                $filename,
60                $options['description'],
61                $executableContext,
62                $result
63            );
64        }
65
66    } catch (PharException $e) {
67        // Phar拡張が有効でない場合、または書き込み権限がない場合に発生する可能性があります。
68        echo "PharException: " . $e->getMessage() . "\n";
69        echo "Phar拡張が有効で、スクリプト実行ディレクトリに書き込み権限があるか確認してください。\n";
70        echo "補足: isValidPharFilenameメソッドの利用自体には実際のアーカイブファイルの内容は不要ですが、\n";
71        echo "PharDataインスタンスの作成時にファイルシステムへのアクセスが必要となることがあります。\n";
72    } catch (Exception $e) {
73        // その他の予期せぬ例外を捕捉
74        echo "予期せぬエラー: " . $e->getMessage() . "\n";
75    } finally {
76        // スクリプト終了時に作成した一時ファイルを確実に削除します。
77        if (file_exists($dummyArchiveFile)) {
78            unlink($dummyArchiveFile);
79            echo "\n一時ファイル '{$dummyArchiveFile}' を削除しました。\n";
80        }
81    }
82}
83
84// 関数の実行
85checkPharFilenameValidity();
86

PHPのPharData::isValidPharFilenameメソッドは、与えられたファイル名がPHPのPhar（PHP Archive）形式として妥当な命名規則に従っているかを判断するために使用されます。このメソッドは、ファイル名 $filename が指定されたルールに合致するかをチェックし、結果を真偽値（trueまたはfalse）で返します。

具体的には、ファイル名が.phar、.phar.gz、.phar.bz2のようなPharアーカイブ特有の拡張子を含んでいるかなどを確認します。第2引数 $executable を true にすると、そのファイルが実行可能なPharアーカイブとして有効かを厳しくチェックし、falseにすると、より広範なPharDataが扱えるアーカイブ（例：tarやzip）のファイル名形式も許容するかどうかを考慮します。

重要な点として、このメソッドはファイル名文字列の形式のみを検査します。実際にその名前のファイルが存在するか、またはファイルの中身が正しいPharアーカイブであるかまでは確認しません。

サンプルコードでは、このメソッドがPharDataクラスのインスタンスメソッドであるため、まずPharDataインスタンスを生成しています。メソッドの呼び出し自体は実際のアーカイブ内容には依存しませんが、インスタンス作成のために一時的なダミーファイルを使用している点にご留意ください。これにより、例えばユーザーがアップロードしたファイルの拡張子を事前に検証する際などに、安全かつ効率的なファイル名チェックが可能になります。

Copy
1<?php
2
3/**
4 * PharData::isValidPharFilename() メソッドの使用例
5 *
6 * このメソッドは、与えられたファイル名がPhar (PHP Archive) または
7 * PharDataが扱えるアーカイブ（tar, zip）の命名規則に準拠しているかをチェックします。
8 *
9 * PharDataクラスはPharクラスを継承しており、Phar::isValidPharFilename() が静的メソッドであるため、
10 * PharData::isValidPharFilename() も静的メソッドとして呼び出すことができます。
11 *
12 * 主に、Pharアーカイブを作成したり開いたりする前に、
13 * ファイル名が妥当な形式であるかを確認するために使用されます。
14 */
15
16/**
17 * ファイル名の妥当性をチェックし、結果を出力する関数
18 *
19 * @param string $filename チェックするファイル名
20 * @param bool $executable 実行可能ファイル名として許可するかどうか (デフォルト: true)
21 * @return void
22 */
23function checkPharFilenameValidity(string $filename, bool $executable = true): void
24{
25    $isValid = PharData::isValidPharFilename($filename, $executable);
26    $execStatus = $executable ? '実行可能考慮' : '実行可能考慮せず';
27    echo sprintf(
28        "ファイル名 '%s' (%s): %s\n",
29        $filename,
30        $execStatus,
31        $isValid ? '有効' : '無効'
32    );
33}
34
35echo "--- Pharファイル名の妥当性チェック --- \n";
36
37// 有効なPharファイル名の例
38checkPharFilenameValidity('my_app.phar');
39checkPharFilenameValidity('project.phar.gz'); // 圧縮形式も考慮される
40checkPharFilenameValidity('library.phar.bz2');
41checkPharFilenameValidity('backup.tar');      // PharDataで扱えるtarアーカイブも有効
42checkPharFilenameValidity('web_app.zip');     // PharDataで扱えるzipアーカイブも有効
43checkPharFilenameValidity('script.phar.php'); // PHPスクリプトとして実行可能なPharファイル名
44
45echo "\n--- 無効なPharファイル名の例 --- \n";
46
47// 無効なPharファイル名の例
48checkPharFilenameValidity('document.txt');      // 拡張子がPhar関連ではない
49checkPharFilenameValidity('data.log');
50checkPharFilenameValidity('no_extension');      // 拡張子がない
51checkPharFilenameValidity('.phar');             // ファイル名がない
52checkPharFilenameValidity('foo.ph');            // 不完全なPhar拡張子
53checkPharFilenameValidity('my_app.phpar');      // 認識されない拡張子
54
55echo "\n--- 実行可能フラグ (\$executable) のテスト --- \n";
56
57// 第二引数 $executable は、ファイル名がPHPによって直接実行可能であると
58// 見なされる拡張子（例: .phar.php, .phar.inc）を持つPharファイル名を
59// 許可するかどうかを制御します。
60
61// 'my_script.phar.php' はPHPで実行可能なPharファイル名です。
62checkPharFilenameValidity('my_script.phar.php', true);  // 実行可能考慮: 有効
63checkPharFilenameValidity('my_script.phar.php', false); // 実行可能考慮せず: 無効になる
64
65// 'app.phar' は一般的に実行可能なPharと見なされますが、
66// 特定の実行可能拡張子 (.php など) を持たないため、executable=false でも有効と判断される場合があります。
67checkPharFilenameValidity('app.phar', true);  // 実行可能考慮: 有効
68checkPharFilenameValidity('app.phar', false); // 実行可能考慮せず: 有効
69
70// 'data.phar.txt' は .txt 拡張子のため実行可能と見なされません。
71checkPharFilenameValidity('data.phar.txt', true);  // 実行可能考慮: 無効 (Phar拡張子とはみなされない)
72checkPharFilenameValidity('data.phar.txt', false); // 実行可能考慮せず: 無効 (Phar拡張子とはみなされない)
73
74?>

PHP 8のPharData::isValidPharFilename()メソッドは、与えられたファイル名がPhar（PHPアーカイブ）形式、またはPharDataが扱えるtarやzip形式のアーカイブとして妥当な命名規則に沿っているかを判定します。このメソッドは静的に呼び出すことができます。

第一引数$filenameには、妥当性をチェックしたいファイル名を文字列で指定します。第二引数$executableはオプションで、デフォルトはtrueです。この引数をfalseに設定すると、ファイル名が.phar.phpのようにPHPスクリプトとして直接実行可能な拡張子を持つ場合、Pharファイル名としては無効と判断されます。メソッドは、ファイル名がPharアーカイブとして妥当であればtrueを、そうでなければfalseをブール値で返します。

例えば、my_app.pharやproject.phar.gz、backup.tar、web_app.zipなどのファイル名は有効と判断されます。しかし、document.txtや拡張子がないno_extensionなどは無効です。script.phar.phpのように実行可能なPharファイル名は、$executableがtrueの時には有効ですが、falseにすると無効と判定される点に注意が必要です。このメソッドは、主にPharアーカイブを作成したり開いたりする前に、ファイル名の形式が適切かを確認するために活用されます。