【PHP8.x】stat()関数の使い方

Copy
1<?php
2
3/**
4 * stat関数を使用してファイルの静的な情報を取得し、表示するサンプルコードです。
5 *
6 * このコードは一時ファイルを作成し、そのファイルに対してstat関数を実行します。
7 * stat関数は、ファイルサイズ、最終更新日時、パーミッションなどの詳細なファイルシステム情報を提供します。
8 * キーワード「static」は、ファイルシステムにおける「静的な情報」（ファイルの属性など）を指します。
9 */
10
11// 検査対象となるファイルパスを定義します。
12$filename = 'temp_example_for_stat.txt';
13
14// サンプル実行のために一時ファイルが存在しない場合は作成します。
15// これにより、コードが単体で動作し、常にstat関数が検査できるファイルがある状態を保証します。
16if (!file_exists($filename)) {
17    file_put_contents($filename, "これはstat関数を試すための一時ファイルです。\nPHPの静的なファイル情報を確認します。");
18    echo "一時ファイル '$filename' を作成しました。\n\n";
19}
20
21// stat関数を呼び出して、ファイルの静的な情報を取得します。
22// 成功した場合、ファイルの情報を含む連想配列を返します。
23// 失敗した場合は (例: ファイルが存在しない、アクセス権がないなど)、false を返します。
24$fileStats = stat($filename);
25
26// stat関数の戻り値がfalseでないかチェックし、エラーハンドリングを行います。
27if ($fileStats !== false) {
28    echo "ファイル '$filename' の静的な情報:\n";
29    echo "--------------------------\n";
30
31    // ファイルサイズ (バイト単位)
32    echo "ファイルサイズ: " . $fileStats['size'] . " バイト\n";
33
34    // 最終更新日時 (Unixタイムスタンプを人間が読める形式に変換)
35    echo "最終更新日時: " . date('Y-m-d H:i:s', $fileStats['mtime']) . "\n";
36
37    // 最終アクセス日時 (Unixタイムスタンプを人間が読める形式に変換)
38    echo "最終アクセス日時: " . date('Y-m-d H:i:s', $fileStats['atime']) . "\n";
39
40    // inode変更日時 (Unixタイムスタンプを人間が読める形式に変換)
41    // inodeはファイルシステム上のファイルのメタデータ情報を保持する構造です。
42    echo "inode変更日時: " . date('Y-m-d H:i:s', $fileStats['ctime']) . "\n";
43
44    // ファイルのパーミッション (八進数表記)
45    // & 0777 を使うことで、ファイルの種類を示すビットを除外し、純粋なパーミッションのみを表示します。
46    echo "パーミッション (八進数): " . sprintf('%o', $fileStats['mode'] & 0777) . "\n";
47
48    // ファイルのデバイスID (ファイルが存在するデバイスのID)
49    echo "デバイスID: " . $fileStats['dev'] . "\n";
50
51    // ファイルのinode番号 (ファイルシステム内でファイルを一意に識別する番号)
52    echo "inode番号: " . $fileStats['ino'] . "\n";
53
54    // ファイルへのハードリンク数
55    echo "ハードリンク数: " . $fileStats['nlink'] . "\n";
56
57    // ファイルの所有者のユーザーID (UID)
58    echo "所有者 (UID): " . $fileStats['uid'] . "\n";
59
60    // ファイルの所有グループのグループID (GID)
61    echo "グループ (GID): " . $fileStats['gid'] . "\n";
62
63    // その他、['blksize', 'blocks'] などの情報も取得できます。
64
65} else {
66    // stat関数がfalseを返した場合のエラーメッセージ
67    echo "エラー: ファイル '$filename' の情報を取得できませんでした。\n";
68    echo "ファイルが存在しないか、スクリプトにアクセス権がありません。\n";
69}
70
71// サンプル用に作成した一時ファイルを削除します。
72// これにより、スクリプトの実行後に不要なファイルが残らないようにします。
73if (file_exists($filename)) {
74    unlink($filename);
75    echo "\n一時ファイル '$filename' を削除しました。\n";
76}
77
78?>

PHPのstat関数は、指定されたファイルの「静的な情報」を取得するために用いられます。ここでいう静的な情報とは、ファイルサイズ、最終更新日時、アクセス日時、ファイルのパーミッション（アクセス権）、所有者IDやグループIDといった、ファイルシステム上でファイルに紐づけられている固定の属性を指します。

この関数は、引数として検査したいファイルのパスを文字列（string $filename）で受け取ります。処理が成功すると、取得したファイル情報が格納された連想配列（array）を返します。この配列には、ファイルサイズはsizeキー、最終更新日時はmtimeキーのように、様々な情報が具体的なキーで格納されています。もしファイルが存在しない、またはアクセス権がないなどの理由で情報の取得に失敗した場合は、戻り値としてfalseが返されるため、戻り値の確認によるエラーハンドリングが重要です。

提供されたサンプルコードでは、まず一時ファイルを作成し、そのファイルに対してstat関数を実行しています。取得した情報からファイルサイズや最終更新日時などを整形して表示し、stat関数がどのような情報を提供するのかを具体的に示しています。また、エラー発生時のメッセージ表示や、サンプル実行後に一時ファイルを適切に削除する処理も含まれており、実用的なプログラミングの例として学ぶことができます。この関数は、ファイル管理ツールやバックアップシステムなど、ファイルシステムの詳細な属性を扱う際に非常に役立ちます。

Copy
1<?php
2
3/**
4 * ファイルシステム操作に関連するユーティリティ機能を提供するクラス。
5 * このクラスのメソッドは静的であり、インスタンスを生成せずに直接呼び出すことができます。
6 * システムエンジニアを目指す初心者の方へ：
7 * static function（静的メソッド）は、クラスのインスタンス（オブジェクト）を作成せずに
8 * クラス名を介して直接呼び出せる関数です。ファイル操作のような汎用的な機能でよく使用されます。
9 */
10class FileUtil
11{
12    /**
13     * 指定されたファイルの統計情報を取得します。
14     * PHPの標準関数である stat() の結果を返します。
15     * stat()関数は、ファイルに関する詳細な情報（サイズ、パーミッション、最終更新日時など）を配列で返します。
16     *
17     * @param string $filename 検査するファイルのパス。
18     * @return array|false 成功した場合はファイル統計情報を含む連想配列、失敗した場合はfalse。
19     */
20    public static function getFileStat(string $filename): array|false
21    {
22        // stat()関数を呼び出してファイルの統計情報を取得します。
23        // ファイルが存在しない、またはアクセス権がない場合はfalseが返されます。
24        $statInfo = stat($filename);
25
26        // 統計情報の取得に失敗した場合は、そのままfalseを呼び出し元に返します。
27        if ($statInfo === false) {
28            return false;
29        }
30
31        // 成功した場合は、取得した統計情報の配列を返します。
32        return $statInfo;
33    }
34}
35
36// --- 以下はサンプルコードの実行部分です ---
37
38// 1. 存在するファイルの統計情報を取得する例
39// このスクリプト自身のパスを対象としています。
40$existingFile = __FILE__;
41$fileStat = FileUtil::getFileStat($existingFile);
42
43if ($fileStat !== false) {
44    echo "--- 存在するファイルの統計情報 ---\n";
45    echo "ファイルパス: " . $existingFile . "\n";
46    echo "ファイルサイズ: " . $fileStat['size'] . " バイト\n";
47    echo "最終更新日時: " . date('Y-m-d H:i:s', $fileStat['mtime']) . "\n";
48    // $fileStat配列には他にも多くの情報が含まれています。
49    // 必要に応じて print_r($fileStat); で内容を確認できます。
50} else {
51    echo "エラー: 存在するファイル '" . $existingFile . "' の統計情報取得に失敗しました。\n";
52}
53
54echo "\n"; // 区切りのための改行
55
56// 2. 存在しないファイルの統計情報を取得する例
57$nonExistingFile = 'non_existent_file_for_test.txt'; // 存在しないファイルを指定
58$fileStat = FileUtil::getFileStat($nonExistingFile);
59
60if ($fileStat !== false) {
61    // このブロックは通常、ファイルが存在しないため実行されません。
62    echo "--- 存在しないファイルの情報 (予期せぬ成功) ---\n";
63    print_r($fileStat);
64} else {
65    echo "--- 存在しないファイルの統計情報 ---\n";
66    echo "ファイルパス: " . $nonExistingFile . "\n";
67    echo "メッセージ: 統計情報取得に失敗しました。ファイルが存在しないか、アクセスできません。\n";
68}
69
70?>

このPHPのサンプルコードは、stat()関数を利用してファイルの統計情報を取得する方法を、システムエンジニアを目指す初心者の方にも分かりやすく示すものです。FileUtilクラスに定義されたgetFileStatメソッドは、public static function（公開静的メソッド）として作成されています。静的メソッドは、クラスのインスタンス（オブジェクト）を生成することなく、クラス名であるFileUtilを介して直接呼び出すことができるため、ファイル操作のような汎用的な機能に適しています。

getFileStatメソッドは、引数としてstring $filename、つまり検査したいファイルのパスを受け取ります。そして、PHPの標準関数であるstat()を内部で呼び出し、指定されたファイルのサイズ、最終更新日時、パーミッションなどの詳細な情報を配列として取得します。このメソッドの戻り値はarray|falseであり、ファイルの情報が正常に取得できた場合は統計情報を含む連想配列が返されます。しかし、ファイルが存在しない場合やアクセス権がないなどの理由で情報取得に失敗した場合は、falseが返される仕組みです。

サンプルコードの実行部分では、まず現在実行中のスクリプト自身のファイルパスを指定して、存在するファイルの統計情報を取得し、そのサイズや最終更新日時を表示する例が示されています。次に、存在しないファイル名を指定してgetFileStatメソッドを呼び出し、falseが返されることでエラー処理が行われる様子も確認できます。このコードは、プログラムでファイルの状態を確認し、結果に応じて適切な処理を行うための基本的な流れを理解するのに役立ちます。

Copy
1<?php
2
3/**
4 * 指定されたファイルの stat 情報を取得します。
5 * 同じファイルが複数回要求された場合、関数内の静的変数にキャッシュされた情報を返します。
6 * これは、ディスクI/Oを伴う stat コールを減らし、パフォーマンスを向上させる一般的なパターンです。
7 *
8 * @param string $filename 情報を取得するファイルへのパス。
9 * @return array|false ファイルの stat 情報を含む配列、またはエラー時に false。
10 */
11function get_file_stat_cached(string $filename): array|false
12{
13    // static 変数は、関数が呼び出されるたびに初期化されず、
14    // 関数が最初に呼び出されたときに一度だけ初期化され、
15    // その状態を保持します。ここではファイル情報のキャッシュに使用します。
16    static $cache = [];
17
18    // キャッシュにファイル情報が存在するかチェック
19    if (isset($cache[$filename])) {
20        echo "DEBUG: '{$filename}' の stat 情報はキャッシュから取得されました。\n";
21        return $cache[$filename];
22    }
23
24    // キャッシュに存在しない場合、stat 関数を呼び出して情報を取得
25    echo "DEBUG: '{$filename}' の stat 情報は新たに取得されました。\n";
26    $file_stat = stat($filename);
27
28    // stat が失敗した場合（例: ファイルが存在しない）
29    if ($file_stat === false) {
30        error_log("ERROR: stat() failed for file: {$filename}");
31        return false;
32    }
33
34    // 取得した情報をキャッシュに保存
35    $cache[$filename] = $file_stat;
36
37    return $file_stat;
38}
39
40// --- サンプルコードの実行 ---
41
42// 一時ファイルを作成し、テストの対象とする
43$temp_file = __DIR__ . '/temp_test_file.txt';
44file_put_contents($temp_file, 'This is a test file.');
45
46echo "--- 1回目の stat 取得 (キャッシュなし) ---\n";
47$stat_info_1 = get_file_stat_cached($temp_file);
48if ($stat_info_1) {
49    echo "ファイルサイズ: " . $stat_info_1['size'] . " バイト\n";
50} else {
51    echo "ファイル情報を取得できませんでした。\n";
52}
53echo "\n";
54
55echo "--- 2回目の stat 取得 (キャッシュ利用) ---\n";
56$stat_info_2 = get_file_stat_cached($temp_file);
57if ($stat_info_2) {
58    echo "ファイルサイズ: " . $stat_info_2['size'] . " バイト\n";
59} else {
60    echo "ファイル情報を取得できませんでした。\n";
61}
62echo "\n";
63
64echo "--- 別のファイルの stat 取得 (キャッシュなし) ---\n";
65$another_file = __DIR__ . '/another_test_file.txt';
66file_put_contents($another_file, 'Another file.');
67$stat_info_3 = get_file_stat_cached($another_file);
68if ($stat_info_3) {
69    echo "ファイルサイズ: " . $stat_info_3['size'] . " バイト\n";
70} else {
71    echo "ファイル情報を取得できませんでした。\n";
72}
73echo "\n";
74
75echo "--- 3回目の stat 取得 (最初のファイル、キャッシュ利用) ---\n";
76$stat_info_4 = get_file_stat_cached($temp_file);
77if ($stat_info_4) {
78    echo "ファイルサイズ: " . $stat_info_4['size'] . " バイト\n";
79} else {
80    echo "ファイル情報を取得できませんでした。\n";
81}
82echo "\n";
83
84echo "--- 存在しないファイルの stat 取得 ---\n";
85$non_existent_file = __DIR__ . '/non_existent_file.txt';
86$stat_info_error = get_file_stat_cached($non_existent_file);
87if ($stat_info_error === false) {
88    echo "'{$non_existent_file}' のファイル情報を取得できませんでした (期待される動作)。\n";
89}
90echo "\n";
91
92// テスト用の一時ファイルをクリーンアップ
93unlink($temp_file);
94unlink($another_file);
95
96?>

このPHPコードは、ファイルの情報を取得するstat関数と、関数内でのみ値を保持し続けるstatic変数を組み合わせて、処理の効率化を図るパターンを示しています。PHPのstat関数は、指定されたファイルパス（string $filename）のサイズや最終更新日時などの詳細な統計情報を配列（array）として返しますが、ファイルシステムへのアクセスが伴うため、頻繁な呼び出しはパフォーマンスに影響を及ぼす可能性があります。

このサンプルコードのget_file_stat_cached関数は、このstat関数の呼び出し回数を減らすことを目的としています。関数内で宣言されたstatic $cache = [];は、一度初期化されると、その後の関数呼び出しの間もその状態を保持し続ける特殊な変数です。

get_file_stat_cached関数は、引数としてファイルパス（string $filename）を受け取ります。まず、この$filenameに対応する情報が$cache配列に存在するかを確認します。もし存在すれば、ディスクにアクセスすることなく、キャッシュされた情報をarrayとして即座に返します。情報がキャッシュされていない場合は、PHPの組み込み関数stat($filename)を呼び出してファイル情報を新たに取得します。stat関数がファイルが見つからないなどの理由で失敗した場合、get_file_stat_cached関数はfalseを返します。成功した場合は、取得した情報を$cacheに保存してからarrayとして返します。この仕組みにより、同じファイルに対して複数回情報を要求しても、初回のアクセス時以外は高速に処理され、システム全体の負荷が軽減されます。

Copy
1<?php
2
3/**
4 * PHPのstat()関数を使用して、指定されたファイルの情報を取得するサンプルコードです。
5 * stat()関数は、ファイルシステムの「静的な状態」（サイズ、最終更新日時など）を配列として返します。
6 * この関数はPHPの標準機能であり、特定のクラスの静的メソッドではありませんが、
7 * ファイルの状態（ファイルシステムが提供する特定の時点での情報）を取得するという意味で、
8 * 「静的」な情報取得と関連付けて理解することができます。
9 *
10 * @param string $filename 情報取得の対象となるファイルのパス
11 * @return void
12 */
13function displayFileStats(string $filename): void
14{
15    // 事前準備: このスクリプトを実行する前に、指定したパスにファイルが存在することを確認してください。
16    // 例: このPHPファイルと同じディレクトリに 'my_document.txt' というファイルを作成し、
17    // 何らかのテキスト（例: "Hello PHP!"）を書き込んでから実行してください。
18    // コマンドラインから作成する例: echo "Hello PHP!" > my_document.txt
19
20    echo "ファイル '{$filename}' の情報を取得します...\n";
21
22    // stat() 関数を呼び出し、ファイルの統計情報を取得します。
23    // 成功した場合はファイルの情報を格納した配列を、失敗した場合は false を返します。
24    $stats = stat($filename);
25
26    if ($stats === false) {
27        // stat() が false を返した場合、ファイルが見つからないか、
28        // アクセス権がないなどの問題が発生しています。
29        echo "エラー: ファイル '{$filename}' の情報を取得できませんでした。\n";
30        echo "ヒント: 指定したファイルが存在するか、PHPスクリプトからアクセスする権限があるか確認してください。\n";
31    } else {
32        echo "--- 取得されたファイル情報 ---\n";
33        echo "  ファイル名: " . basename($filename) . "\n";
34        echo "  ファイルサイズ: " . $stats['size'] . " バイト\n";
35        echo "  最終アクセス時刻: " . date('Y-m-d H:i:s', $stats['atime']) . "\n";
36        echo "  最終変更時刻: " . date('Y-m-d H:i:s', $stats['mtime']) . "\n";
37        // iノード変更時刻 (inode change time) は、ファイルのメタデータが変更された時刻です。
38        echo "  最終iノード変更時刻: " . date('Y-m-d H:i:s', $stats['ctime']) . "\n";
39        // パーミッション (モード) の表示。
40        // mode の値にはファイルタイプ（例: 通常ファイル、ディレクトリ）も含まれるため、
41        // 0777 とAND演算してパーミッション部分（所有者、グループ、その他の権限）のみを抽出します。
42        echo "  パーミッション (8進数): " . sprintf('%o', $stats['mode'] & 0777) . "\n";
43        echo "----------------------------\n";
44
45        // stat()関数が返す全ての詳細な情報を確認したい場合は、以下の行のコメントを解除してください。
46        // echo "--- 全ての詳細情報 ---\n";
47        // var_dump($stats);
48        // echo "----------------------\n";
49    }
50}
51
52// このサンプルコードを実行するには、実際に存在するファイルのパスを指定してください。
53// 例として、このPHPファイルと同じディレクトリにある 'example.txt' を指定します。
54displayFileStats('example.txt');

PHPのstat()関数は、指定されたファイルやディレクトリの「静的な状態」に関する詳細な情報を取得するための関数です。ここで言う「静的な状態」とは、ファイルシステムが提供する特定の時点でのファイルサイズ、最終更新日時、アクセス権限などのメタデータを指します。この関数は特定のクラスに属する静的メソッドではありませんが、ファイルシステム上の固定された時点での情報を取得するという意味で、「静的な情報」を扱います。

引数には情報取得の対象となるファイルのパスを文字列で渡します。関数が成功すると、ファイルに関する様々な情報（例: ファイルサイズ、最終アクセス時刻、最終変更時刻、パーミッションなど）が格納された連想配列または数値添字配列が返されます。もし指定されたファイルが存在しない場合や、アクセス権限がないなどの理由で情報の取得に失敗した場合は、falseが返されます。

サンプルコードでは、displayFileStats()関数がファイルパスを受け取り、stat()関数を呼び出してそのファイルの情報を取得しています。取得に成功した場合は、ファイル名、サイズ、最終更新日時、パーミッションといった主要な情報を整形して表示します。もしstat()関数がfalseを返した場合は、ファイルが見つからないかアクセスできない旨のエラーメッセージを表示し、適切な確認を促しています。これにより、stat()関数の基本的な使い方とともに、戻り値に応じたエラーハンドリングの重要性も理解できます。