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.