PHP stat Function
last modified April 3, 2025
The PHP stat function retrieves file status information. It returns
an array with detailed statistics about a file or symbolic link.
Basic Definition
The stat function gathers information about a file. It returns an
associative array with numeric and string indices containing file statistics.
Syntax: stat(string $filename): array|false. Returns false on
failure. The array contains 13 elements with both numeric and named keys.
Basic stat Example
This example shows how to get basic file information using stat.
<?php
declare(strict_types=1);
$file = 'example.txt';
$stats = stat($file);
if ($stats !== false) {
echo "File size: " . $stats['size'] . " bytes\n";
echo "Last modified: " . date('Y-m-d H:i:s', $stats['mtime']);
}
This retrieves the file size and modification time. The size is in
bytes, and mtime is a Unix timestamp converted to readable format.
Checking File Type
We can use stat to determine if a path is a file or directory.
<?php
declare(strict_types=1);
$path = 'example.txt';
$stats = stat($path);
if ($stats !== false) {
$mode = $stats['mode'];
if (($mode & 0x4000) === 0x4000) {
echo "This is a directory";
} else {
echo "This is a regular file";
}
}
This checks the file mode bits to determine the type. The bitmask 0x4000 identifies directories in Unix-like systems.
File Permissions
stat can be used to check file permissions.
<?php
declare(strict_types=1);
$file = 'example.txt';
$stats = stat($file);
if ($stats !== false) {
$permissions = $stats['mode'] & 0777;
echo "Permissions: " . decoct($permissions);
}
This extracts the permission bits from the mode. The octal representation shows Unix-style permissions like 644 or 755.
File Access Times
The function provides three different timestamps for file access.
<?php
declare(strict_types=1);
$file = 'example.txt';
$stats = stat($file);
if ($stats !== false) {
echo "Created: " . date('Y-m-d H:i:s', $stats['ctime']) . "\n";
echo "Modified: " . date('Y-m-d H:i:s', $stats['mtime']) . "\n";
echo "Accessed: " . date('Y-m-d H:i:s', $stats['atime']);
}
This displays creation, modification, and access times. Note that ctime
on Unix is inode change time, not creation time.
Symbolic Link Stats
stat follows symbolic links by default. Use lstat for
link information.
<?php
declare(strict_types=1);
$link = 'symlink_to_file';
$stats = lstat($link);
if ($stats !== false) {
echo "Link size: " . $stats['size'] . " bytes\n";
echo "Is symlink: " . (is_link($link) ? 'Yes' : 'No');
}
This shows how to get information about the symbolic link itself rather than
the target file. The size here is the length of the link path.
Best Practices
- Error Handling: Always check if stat returns false.
- Performance: Cache results for repeated access.
- Security: Validate paths before processing.
- Cross-platform: Be aware of system differences.
Source
This tutorial covered the PHP stat function with practical
examples showing its usage for file information retrieval.