ファイルに関する情報を取得する

# stat

(PHP 4, PHP 5, PHP 7, PHP 8)

stat — ファイルに関する情報を取得する

### 説明

function stat(string `$filename`): array|false

`filename`で指定されたファイルに ついての統計情報を取得します。 `filename` がシンボリックリンクの場合、 シンボリックリンクではなくファイルの実体の統計情報が返されます。 Windows 環境、かつ PHP 7.4.0 より前の NTS ビルドでは、 `size`, `atime`, `mtime`, `ctime` の統計情報は、シンボリックリンクの値が返されていました。

lstat() はシンボリックリンクの統計情報を返すという違いを除いて stat() と等価です。

### パラメータ

`filename`

  ファイルへのパス。

### 戻り値

stat() と fstat() の結果のフォーマット
数値 | 連想配列 | 説明
--- | --- | ---
0 | dev | デバイス番号 (***)
1 | ino | inode 番号(****)
2 | mode | inode プロテクトモード(*****)
3 | nlink | リンク数
4 | uid | 所有者のユーザー ID(*)
5 | gid | 所有者のグループ ID(*)
6 | rdev | inode デバイス の場合、デバイスの種類
7 | size | バイト単位のサイズ
8 | atime | 最終アクセス時間 (Unix タイムスタンプ)
9 | mtime | 最終修正時間 (Unix タイムスタンプ)
10 | ctime | 最終 inode 変更時間 (Unix タイムスタンプ)
11 | blksize | ファイル IO のブロックサイズ(**)
12 | blocks | 512 バイトのブロックの確保数(**)

* Windows では常に `0` となります。

** st_blksize タイプをサポートするシステムでのみ有効です。 その他のシステム(例えば Windows)では `-1` を返します。

*** PHP 7.4.0 以降、Windows では、この値はファイルが含まれるボリュームのシリアル番号です。 これは64ビットの 符号なし 整数です。 よって、オーバーフローする可能性があります。 これより前のバージョンでは、stat() 関数ではドライブレターを数値で表現した値 (たとえば、`C:` では `2`) でした。 lstat() 関数では `0` でした。

**** PHP 7.4.0 以降、Windows では、この値はファイルに関連付けられた識別子です。 これは64ビットの 符号なし 整数です。 よって、オーバーフローする可能性があります。 これより前のバージョンでは、この値は常に `0` でした。

***** Windows では、 読み取り専用のファイル属性に従って、 書き込み可能のパーミッションビットが設定されます。 そして、この値は全てのユーザ、グループ、 オーナーについて、同じ値が報告されます。 is_writable() とは異なり、ACL は考慮されません。

`mode` の値は、複数の関数によって読まれる情報が含まれています。 8進数の場合、一番右の桁から評価され、はじめの3桁が chmod() によって返されます。 次の桁は PHP によって無視されます。その次の2桁は以下のファイルタイプを示します:

`mode` のファイルタイプ
`mode` が8進数だった場合 | 意味
--- | ---
`0140000` | ソケット
`0120000` | リンク
`0100000` | 通常のファイル
`0060000` | ブロックデバイス
`0040000` | ディレクトリ
`0020000` | キャラクタデバイス
`0010000` | fifo

よって、たとえば 通常のファイルは `0100644` のような値になりますし、 ディレクトリは `0040755` のような値になります。

stat() はエラーの場合 `false` を返します。

> 注意: PHP の数値型は符号付整数であり、 多くのプラットフォームでは 32 ビットの整数を取るため、 ファイルシステム関数の中には 2GB より大きなファイルについては期待とは違う値を返すものがあります。

### エラー / 例外

失敗した場合は `E_WARNING` が発生します。

### 変更履歴

バージョン | 説明
--- | ---
7.4.0 | Windows では、 デバイス番号は、ファイルが含まれるボリュームのシリアル番号を返すようになりました。 そして、inode 番号は、ファイルに関連付けられた識別子を返すようになりました。
7.4.0 | シンボリックリンクの場合、 `size`, `atime`, `mtime`, `ctime` の統計情報は、ファイルの実体の値が返されるようになりました。 これより前のバージョンの Windows NTS ビルドはそうではありませんでした。

### 例

例1 stat() の例

    <?php
    /* ファイルの状態を取得します */
    $stat = stat('C:\php\php.exe');

    /*
     * ファイルのアクセス日時を表示します。
     * これは fileatime() をコールするのと同じです
     */
    echo 'アクセス日時: ' . $stat['atime'];

    /*
     * ファイルの更新日時を表示します。
     * これは filemtime() をコールするのと同じです
     */
    echo '更新日時: ' . $stat['mtime'];

    /* デバイス番号を表示します */
    echo 'デバイス番号: ' . $stat['dev'];
    ?>

例2 stat() の情報を touch() と組み合わせる例

    <?php
    /* ファイルの状態を取得します */
    $stat = stat('C:\php\php.exe');

    /* 情報の取得に失敗した? */
    if (!$stat) {
        echo 'stat() のコールに失敗しました...';
    } else {
        /*
         * アクセス日時を、現在のアクセス日時の
         * 一週間後に設定します
         */
        $atime = $stat['atime'] + 604800;

        /* ファイルを作成します */
        if (!touch('some_file.txt', time(), $atime)) {
            echo 'ファイルの作成に失敗しました...';
        } else {
            echo 'touch() が成功しました...';
        }
    }
    ?>

### 注意

> 注意: 時刻の精度は、 ファイルシステムによって異なることがあります。

> 注意: この関数の結果は キャッシュされます。詳細は、clearstatcache() を参照してください。

ヒント

`PHP 5.0.0` 以降、この関数は、 何らかの URL ラッパーと組合せて使用することができます。 どのラッパーが stat() ファミリーをサポートしているかを調べるには サポートするプロトコル/ラッパー を参照してください。

### 参考

- lstat() - ファイルあるいはシンボリックリンクの情報を取得する
- fstat() - オープンしたファイルポインタからファイルに関する情報を取得する
- filemtime() - ファイルの更新時刻を取得する
- filegroup() - ファイルのグループを取得する
- SplFileInfo

`↑` and `↓` to navigate • `Enter` to select • `Esc` to close • `/` to open