PHP stat() Function

Beginner
5 min read
Updated: Nov 2026
3 examples
Filesystem

Definition

In PHP, stat() returns detailed information about a file or folder, such as its size, permissions and last modified time.

The result is one array that holds everything the system knows about the file. Each value is available both by number and by name, so you can use $info['size'] or $info[7].

Syntax

Call stat() with the values you need. Start with this line.

PHP
$info = stat('report.txt');
CallWhat it does
stat('report.txt')Returns an array with size, mode, uid, mtime and other details.
stat('report.txt')['size']Gets only the size of the file in bytes.
stat('missing.txt')Returns false and raises a warning because the file does not exist.

The array contains these named keys: dev, ino, mode, nlink, uid, gid, rdev, size, atime, mtime, ctime, blksize and blocks. The same values are also available by index from 0 to 12. PHP caches the result, so call clearstatcache() if the file changes during the script.

Library declarations
PHP
stat(string $filename): array|false

Parameters

ParameterDescription
filenameRequired. The path to the file or folder. For symbolic links, stat() follows the link and reports on the target.

Return Value

Return ValueDescription
array|falseReturns an array with file information, or false on failure. The array has both numeric and named keys.

PHP Examples

Example 1 — Read Size and Permissions

Create a small file and print its size and permissions with stat().

PHP
<?php
$file = sys_get_temp_dir() . '/stat_demo.txt';
file_put_contents($file, 'Hello');
chmod($file, 0644);

$info = stat($file);

echo 'Size: ', $info['size'], ' bytes', PHP_EOL;
echo 'Permissions: ', substr(sprintf('%o', $info['mode']), -4), PHP_EOL;

unlink($file);

How It Works

  1. file_put_contents() writes the word Hello, which is 5 bytes long.
  2. chmod() sets the permissions to 0644 so the result is predictable.
  3. stat() returns an array, and $info['size'] holds the file size.
  4. sprintf('%o') turns the mode into octal and substr() keeps the last four digits.

Example 2 — Handle a Missing File

stat() returns false for a file that is not there, so always test the result.

PHP
<?php
$info = @stat(sys_get_temp_dir() . '/no_such_file.txt');

if ($info === false) {
    echo 'stat() returned false', PHP_EOL;
} else {
    echo 'Size: ', $info['size'], PHP_EOL;
}

How It Works

  1. The file no_such_file. txt does not exist.
  2. stat() cannot read it, so it returns false.
  3. The @ operator hides the PHP warning.
  4. The === false check prints a simple message instead.

Example 3 — Named Keys, Index Keys and Time

Show that the size is available in two ways and turn the modified time into a readable date.

PHP
<?php
$file = sys_get_temp_dir() . '/stat_time.txt';
file_put_contents($file, 'Hello');
touch($file, 1700000000);
clearstatcache();

$info = stat($file);

echo 'Size by name: ', $info['size'], PHP_EOL;
echo 'Size by index: ', $info[7], PHP_EOL;
echo 'Modified (UTC): ', gmdate('Y-m-d H:i:s', $info['mtime']), PHP_EOL;

unlink($file);

How It Works

  1. touch() sets the modified time to a fixed Unix timestamp so the output never changes.
  2. clearstatcache() clears old cached information before stat() runs.
  3. $info['size'] and $info[7] are two ways to read the same value.
  4. gmdate() converts the mtime timestamp into a readable UTC date.

Frequently Asked Questions

It returns an array of information about a file or folder, including size, permissions, owner and the access and modified times.
It returns false and raises a warning. Use file_exists() first or compare the result with === false.
Use filesize() for just the size. stat() is better when you need several details at the same time.
stat() follows symbolic links and reports on the target file. lstat() reports on the link itself.
PHP caches file information. Call clearstatcache() if the file changed while your script was running.

Next: symlink()

symlink() creates a symbolic link, which is a shortcut that points to another file or fold.

symlink() tutorial →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

8 people found this page helpful