stat()

Introduction

The stat() function returns a single array containing low-level metadata about a file: its size, permissions, owner, inode, link count, and three timestamps (access, modification, and inode-change). It is PHP's wrapper around the C stat() system call, so it gives you in one call the same information you would otherwise gather from many separate functions like filesize(), filemtime(), and fileperms().

This article covers the syntax, the full meaning of every value stat() returns, the gotchas that trip people up (the stat cache, symbolic links, and string vs. numeric indices), and runnable examples.

Syntax

stat(string $filename): array|false

• $filename — the path to the file you want information about.
• Return value — an array describing the file, or false on failure (for example, the file does not exist or is not readable). Because it can return false, always check the result before indexing into it.

stat() follows symbolic links and reports on the target file. If you need metadata about the link itself, use lstat(). To stat a file you already have an open handle for, use fstat().

What stat() Returns

The returned array is unusual: every value appears twice — once under a numeric index and once under a descriptive string key. So $info[7] and $info['size'] are the same value. This dual indexing exists for backward compatibility; prefer the named keys for readable code.

A few notes:

• mode packs both the file type and the permission bits. To get just the Unix permission bits (like 0644), mask with & 0777; to display them in octal, wrap with decoct().
• ctime is the inode change time (when permissions, ownership, or links last changed) — it is not the file's creation time. Most Unix filesystems do not store a creation time at all.
• The rdev, blksize, and blocks values are not meaningful on Windows.

Example: Reading a File's Metadata

This example creates a temporary file, stats it, and prints the size, permissions, and modification time:

<?php

// Create a small file to inspect.
$path = tempnam(sys_get_temp_dir(), 'demo');
file_put_contents($path, "Hello, stat()!");

$info = stat($path);
if ($info === false) {
    echo "Could not stat the file.";
    exit;
}

echo "Size: {$info['size']} bytes\n";
echo "Permissions: " . decoct($info['mode'] & 0777) . "\n";
echo "Modified: " . date('Y-m-d H:i:s', $info['mtime']) . "\n";

unlink($path); // clean up

Output (the exact permission and time depend on your system):

Size: 14 bytes
Permissions: 600
Modified: 2026-06-21 12:00:00

Always guard against false: passing a missing path produces a warning and false, and indexing false would otherwise throw.

Gotcha: the Stat Cache

For performance, PHP caches the results of stat() and the related file functions. If a file changes during the same script run and you stat it again, you may get stale data. Clear the cache with clearstatcache() before re-reading:

<?php

$path = tempnam(sys_get_temp_dir(), 'demo');
file_put_contents($path, "first");
echo stat($path)['size'], "\n"; // 5

file_put_contents($path, "much longer content");
clearstatcache(true, $path);    // refresh cached metadata
echo stat($path)['size'], "\n"; // 19

unlink($path);

stat() vs. the Single-Purpose Functions

If you only need one piece of information, the dedicated functions are clearer and slightly cheaper:

• File size → filesize()
• Modification time → filemtime()
• Last access time → fileatime()
• Permissions → fileperms()
• File type → filetype()

Reach for stat() when you need several of these at once, since it makes a single system call instead of many. Before stating, you may also want to confirm the path is a real file with is_file() or file_exists().

Conclusion

The stat() function gives you a complete, low-level snapshot of a file's metadata in one call. Remember to check for a false return, use the named array keys for readability, mask mode with & 0777 for permissions, and clear the stat cache if you re-read a file that changed mid-script. When you need just one attribute, prefer the matching single-purpose function.

Practice