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-

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 octal	Meaning
  0140000	Socket
  0120000	Link
  0100000	Regular file
  0060000	Block device
  0040000	Directory
  0020000	Character device
  0010000	Fifo

  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