PHP lstat() Function

What is PHP lstat() Function?

If you want to know file specific information about a file (like last access time, its size, last modification time etc) or a symbolic link. call PHP lstat() function.

What is a symbolic link? A symbolic link is a shortcut of an existing file or folder in your file system. You can think of this similar to Windows shortcut.

Syntax:

lstat(filename)

Parameters:

The Function has 1 parameter which is required-

filename (Required): it is the path to the file or the symbolic link.

Return Values:

If the parameter is a path to a file, the function returns-

  • File information as an array – on success and
  • False – if there happens any error.

In the array, the function returns the following information with the defined keys-

Numeric KeyAssociative keyDescription
0devDevice number on which the file is located.
1infoInode number (identification number) of the file
2modeInode protection mode (File type and permissions)
3nlinkNumber of links
4uiduserid of owner
5gidgroupid of owner
6rdevDevice type, if inode device
7sizeSize in bytes
8atimeTime of last access (Unix timestamp)
9mtimetime of last modification (Unix timestamp)
10ctimetime of last inode change (Unix timestamp)
11blksizeblocksize of filesystem IO
12blocksnumber of 512-byte blocks allocated

If the filename parameter is a symbolic link, the function returns –

  • The status of the symbolic link is returned, not the status of the file pointed to by the symbolic link – on success and
  • False – if there happens any error.

Examples:

Example 1:

<pre>
<?php
print_r(lstat("test.txt"));
echo "<br />";
$target = "file/demo.txt";
$link = 'uploads';
symlink($target, $link);
print_r(lstat($link));
?>
</pre>

Output:

Array(
    [0] => 2065
    [1] => 28131079
    [2] => 41471
    [3] => 1
    [4] => 1851
    [5] => 1847
    [6] => 0
    [7] => 8
    [8] => 1709981960
    [9] => 1709553460
    [10] => 1709553460
    [11] => 4096
    [12] => 0
    [dev] => 2065
    [ino] => 28131079
    [mode] => 41471
   [nlink] => 1
    [uid] => 1851
    [gid] => 1847
    [rdev] => 0
    [size] => 8
    [atime] => 1709981960
    [mtime] => 1709553460
    [ctime] => 1709553460
    [blksize] => 4096
    [blocks] => 0
)

Note: You’ll see a different result which is matched to your server.

Explanation:

There is a file named “demo.txt” in my “file” folder. The lstat() function returns the file specific detail information of the symbolic file “uploads” as elements of an array. It contains same information in both numeric key and string key.

Example 2:

<?php
$target = "test.txt";
$link = "uploads";
symlink($target, $link);
$file = lstat($link);
$access_timestamp = $file['atime'];
echo "The file was last accessed on: " . date("n/j/Y g:i:s a", $access_timestamp);
echo "<br />";
$modify_timestamp = $file['mtime'];
echo "The file was last modified on: " . date("n/j/Y g:i:s a", $modify_timestamp);
?>

Output:

The file was last accessed on: 3/9/2024 5:59:20 am
The file was last modified on: 3/4/2024 6:57:40 am

Explanation:

There is a file named “test.txt” in my current folder.

Line 6: The last access time of the file can be found by the associative key “atime”. We can also get the access time by the index key 8 like $file[8]. It returns the timestamp of the access time. So, we convert this timestamp by date() function to readable date format.

Line 9: The last modification time of the file can be found by the associative key “mtime”. We can also get the modification time by the index key 9 like $file[9]. It returns the timestamp of the modification time. So, we convert this timestamp by date() function to readable date format.

Notes on lstat() Function:

  • On Windows, as of PHP 7.4.0, device number is the serial number of the volume that contains the file, which is a 64-bit unsigned integer, so it may overflow. Previously, it was the numeric representation of the drive letter (e.g. 2 for C:) for stat(), and 0 for lstat().
  • On Windows, as of PHP 7.4.0, inode number is the identifier associated with the file, which is a 64-bit unsigned integer, so may overflow. Previously, it was always 0.
  • On Windows, the writable permission bit is set according to the read-only file attribute, and the same value is reported for all users, group and owner. The ACL is not taken into account, contrary to is_writable().
  • On Windows uid and gid will always be 0.
  • blksize and blocks are valid on systems supporting the st_blksize type – other systems (e.g. Windows) return -1.
  • The value of mode(associative array key) contains information read by several functions. When written in octal, starting from the right, the first three digits are returned by chmod() function. The next digit is ignored by PHP. The next two digits indicate the file type:
    Mode in octalMeaning
    0140000Socket
    0120000Link
    0100000Regular file
    0060000Block device
    0040000Directory
    0020000Character device
    0010000Fifo

    For example, a regular file could be 0100644. So, as the last three digits are 644, so, the permission for the owner, group, and others are 6 (Read+Write), 4 (Read), and 4 (Read) respectively. Also, sixth and fifth digits from the right side are 10, so its a regular file (see the above table).

Caution:

PHP cache the result of the lstat() function. So if you call this function multiple times in a script PHP sends you the cached result. The problem is if existence of the directory, you won’t get the up-to-date result. To get the latest result, clear the cache with clearstatcache() function. Check the code below-

<?php
$target = "test.txt";
$link = "uploads";
symlink($target, $link);
var_dump(lstat($link));
// Some codes.
var_dump(stat($link));
// Some codes.
clearstatcache();
var_dump(stat($link));
// Some codes.
?>

PHP Version Support:

PHP 4, PHP 5, PHP 7, PHP 8

Summary: PHP lstat() Function

Sometime, you need to know file specific information of a file or a symbolic link. In that case, use lstat() function which is a built-in PHP fuilesystem function.

Reference:

https://www.php.net/manual/en/function.lstat.php