stat

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

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

説明

stat(string$filename): array|false

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

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

パラメータ

filename

ファイルへのパス。

返り値

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

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

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

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

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

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

mode のファイルタイプ
mode が8進数だった場合意味
0140000ソケット
0120000リンク
0100000通常のファイル
0060000ブロックデバイス
0040000ディレクトリ
0020000キャラクタデバイス
0010000fifo
よって、たとえば 通常のファイルは 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');


echo 'アクセス日時: ' $stat['atime'];


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