【PHP8.x】Phar::KEY_MODE_MASK定数の使い方

Copy
1<?php
2
3// このサンプルコードは、Pharアーカイブを作成し、
4// その中のファイルエントリのパーミッションから
5// Phar::KEY_MODE_MASK を使用して純粋なアクセスモードを抽出する方法を示します。
6//
7// キーワード "php key()" に関連し、Pharアーカイブのエントリの「キー」（ファイルパス）
8// とその「モード」（アクセス権限）の取得方法を合わせて紹介します。
9
10// 一時的なPharアーカイブのファイル名
11$pharFileName = 'example_archive.phar';
12$pharFilePath = __DIR__ . '/' . $pharFileName;
13
14// 既存のPharアーカイブが存在する場合は、クリーンアップします。
15// これにより、サンプルコードを複数回実行しても問題なく動作します。
16if (file_exists($pharFilePath)) {
17    // Phar::unlinkArchive() は、PharアーカイブとそのStubファイルを安全に削除するための推奨される方法です。
18    Phar::unlinkArchive($pharFilePath);
19    echo "既存のPharアーカイブ '{$pharFilePath}' を削除しました。\n";
20}
21
22try {
23    // 1. 新しいPharアーカイブを作成します（書き込みモード）。
24    // 第二引数 (0) で既存のファイルがある場合の上書きを許可し、第三引数でアーカイブ名を指定します。
25    $phar = new Phar($pharFilePath, 0, $pharFileName);
26
27    // 2. PharアーカイブのStubを設定します。これはアーカイブの起動スクリプトのようなものです。
28    // createDefaultStub() はPHPが提供するデフォルトのStubを生成します。
29    $phar->setStub($phar->createDefaultStub());
30
31    // 3. アーカイブにファイルを追加し、そのパーミッションを設定します。
32    // addFromString() でファイルの内容を追加し、PharFileInfo::chmod() でパーミッションを設定します。
33
34    // ファイル1: 読み取り・書き込み可能なテキストファイル (例: 0644)
35    $phar->addFromString('documents/report.txt', 'This is a test report.');
36    $phar['documents/report.txt']->chmod(0644); // 8進数でパーミッションを設定
37
38    // ファイル2: 実行可能なスクリプト (例: 0755)
39    $phar->addFromString('scripts/run.sh', '#!/bin/bash' . "\necho 'Hello from run.sh'");
40    $phar['scripts/run.sh']->chmod(0755); // 8進数でパーミッションを設定
41
42    // ディレクトリを追加し、パーミッションを設定します。
43    $phar->addEmptyDir('data');
44    $phar['data']->chmod(0755);
45
46    echo "Pharアーカイブ '{$pharFileName}' を作成しました。\n";
47
48    // Pharオブジェクトをnullに設定することで、アーカイブの書き込みを閉じ、変更を保存します。
49    $phar = null;
50
51    // 4. 作成されたPharアーカイブを読み込みモードで開きます。
52    $phar = new Phar($pharFilePath);
53
54    echo "\nPharアーカイブ内のエントリとそのパーミッション情報:\n";
55
56    // 5. Pharアーカイブのエントリをイテレートし、各エントリの情報を表示します。
57    foreach ($phar as $file) {
58        /** @var PharFileInfo $file Pharアーカイブ内の各ファイルやディレクトリの情報を表すオブジェクト */
59
60        // エントリの「キー」を取得します。Pharアーカイブでは通常ファイルパスがキーとなります。
61        // これは PHP の key() 関数とは異なりますが、Pharエントリを一意に識別するキーという意味合いです。
62        $key = $file->getFilename();
63
64        // エントリの元のパーミッション（ファイルタイプ情報を含む）を取得します。
65        // 例: 通常ファイル (0100644), ディレクトリ (0040755)
66        $originalPerms = $file->getPerms();
67
68        // Phar::KEY_MODE_MASK を使用して、元のパーミッションから
69        // 純粋なファイルアクセスモード（読み取り、書き込み、実行権限）を抽出します。
70        // この定数 (値は 0o777 または 511) は、ファイルタイプなどの情報をマスクして、
71        // rwxrwxrwx の9ビット部分のみを取り出すのに役立ちます。
72        $extractedMode = $originalPerms & Phar::KEY_MODE_MASK;
73
74        echo "  キー (パス): {$key}\n";
75        echo "    元のパーミッション (8進): " . sprintf('%07o', $originalPerms) . "\n";
76        echo "    抽出されたファイルモード (8進): " . sprintf('%03o', $extractedMode) . " (マスク値: " . sprintf('%03o', Phar::KEY_MODE_MASK) . ")\n\n";
77    }
78
79} catch (PharException $e) {
80    // Phar操作中に例外が発生した場合の処理
81    echo "Phar操作中にエラーが発生しました: " . $e->getMessage() . "\n";
82} finally {
83    // 処理の成功失敗に関わらず、最後にPharファイルをクリーンアップします。
84    if (file_exists($pharFilePath)) {
85        Phar::unlinkArchive($pharFilePath);
86        echo "最終クリーンアップ: Pharアーカイブ '{$pharFilePath}' を削除しました。\n";
87    }
88}
89

このサンプルコードは、PHPのPhar拡張機能を使用してアーカイブを作成し、その中のファイルエントリのパーミッションから純粋なアクセスモードを抽出する方法を示しています。特にPhar::KEY_MODE_MASK定数の利用例を通して、ファイルアクセス権限の理解を深めることを目的としています。この定数は引数を取らず、整数値を返すマスク値で、ファイルモードからファイルタイプ情報（ディレクトリかファイルかなど）を取り除き、純粋なrwxrwxrwx形式のアクセス権限のみを抽出する際に使用されます。

コードはまず一時的なPharアーカイブを作成し、異なるパーミッションを持つファイルをいくつか追加します。その後、作成したアーカイブを読み込みモードで開き、各エントリを繰り返し処理しています。それぞれのファイルエントリについて、getFilename()メソッドでエントリの「キー」（ファイルパス）を取得し、getPerms()メソッドでファイルタイプ情報を含む元のパーミッションを取得します。最後に、元のパーミッションとPhar::KEY_MODE_MASK定数をビットAND演算子&で組み合わせることで、純粋なアクセスモードのみを抽出しています。これにより、アーカイブ内の各ファイルの具体的なアクセス権限を正確に把握できることを示しています。

Copy
1<?php
2
3/**
4 * Phar::KEY_MODE_MASK 定数の使用方法を示す関数。
5 *
6 * この定数は、Pharアーカイブ内のエントリのキー（ファイル情報）から
7 * モードビット（パーミッション情報）を抽出するためのビットマスクです。
8 * システムエンジニアを目指す初心者の方へ：
9 * これはPhar（PHPアーカイブ）がファイルやディレクトリの権限情報を
10 * 内部的にどのように管理しているかを示す一例です。
11 * 具体的な値は、どのビットがモードを表すかを示しています。
12 */
13function showPharKeyModeMask(): void
14{
15    // Phar::KEY_MODE_MASK 定数の整数値を表示します。
16    // この値は、Pharアーカイブ内のファイルパーミッションに関連するビットを
17    // 特定するために使用されるマスクです。
18    echo "Phar::KEY_MODE_MASK の値: " . Phar::KEY_MODE_MASK . PHP_EOL;
19}
20
21// 関数を実行して、Phar::KEY_MODE_MASK の値を出力します。
22showPharKeyModeMask();
23
24?>

Phar::KEY_MODE_MASKは、PHPのPhar（PHPアーカイブ）拡張機能に定義されている定数です。この定数は、Pharアーカイブ内に格納されたファイルやディレクトリのエントリ情報、すなわちその「キー」（メタデータ）から、ファイルパーミッション（権限情報）を表すモードビットを正確に抽出するためのビットマスクとして機能する整数値を提供します。システムエンジニアを目指す初心者の方にとって、この定数はPharがファイルシステムにおける権限情報を内部的にどのように管理し、識別しているかを示す具体的な一例となります。

この定数は引数を一切取らず、その評価結果は常にint型の整数値として返されます。この整数値は、ファイルモードに関連する特定のビットだけを抽出するための「マスク」として作用し、Pharアーカイブ内のエントリからパーミッション情報のみを効率的に分離する際に利用されます。

サンプルコードでは、showPharKeyModeMaskという関数内でPhar::KEY_MODE_MASK定数を参照し、その具体的な整数値を画面に出力しています。この出力により、Pharアーカイブがファイルパーミッションを特定するために用いるビットマスクの値が明確に示されます。開発者はこの定数を用いることで、Pharアーカイブに格納されたファイルやディレクトリのアクセス権限をプログラム的に安全かつ正確に操作するための基礎的な情報を得ることができます。