PHP lstat() Function

Beginner
5 min read
Updated: Nov 2026
3 examples
Filesystem

Definition

In PHP, lstat() returns information about a file or a symbolic link, such as its size, owner, permissions and modification time.

It works like stat(), with one big difference: if the path is a symbolic link, lstat() describes the link itself instead of the file it points to.

Syntax

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

PHP
$info = lstat('notes.txt');
CallWhat it does
lstat('notes.txt')Returns an array with the size, times and permissions of notes.txt.
lstat('current')['size']Reads only the size of the item named current.
lstat('missing.txt')Returns false with a warning because the path does not exist.

The result array has both numbered keys (0 to 12) and named keys such as size, mtime, uid, gid, mode and nlink. Use the named keys because they are much easier to read. Results are cached, so call clearstatcache() when a file changes during the same script.

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

Parameters

ParameterDescription
filenameRequired. The path of the file or symbolic link.

Return Value

Return ValueDescription
array|falseReturns an array of file information on success, or false on failure.

PHP Examples

Example 1 — Read the Size of a File

Create a small file and read its size from the lstat() result.

PHP
<?php
$file = __DIR__ . '/hello.txt';
file_put_contents($file, 'Hello');

$info = lstat($file);

echo "Size: ", $info['size'], " bytes", PHP_EOL;

How It Works

  1. file_put_contents() saves the five letters of Hello into hello. txt.
  2. lstat() returns an array of information about the file.
  3. The size key holds the number of bytes.
  4. echo prints that value with a short label.

Example 2 — A Path That Does Not Exist

lstat() returns false for a missing path, so check the result before you use it.

PHP
<?php
$info = @lstat(__DIR__ . '/missing.txt');

var_dump($info);

How It Works

  1. The file does not exist on the disk.
  2. lstat() cannot read it and returns false.
  3. The @ symbol hides the PHP warning for this demo.
  4. In real code, test for false before reading any keys.

Example 3 — Compare stat() and lstat() on a Link

On a symbolic link the two functions give different sizes, because lstat() looks at the link and stat() looks at the target.

PHP
<?php
chdir(__DIR__);

file_put_contents('hello.txt', 'Hello, World!');
@unlink('hello-link.txt');
symlink('hello.txt', 'hello-link.txt');

echo "stat:  ", stat('hello-link.txt')['size'], PHP_EOL;
echo "lstat: ", lstat('hello-link.txt')['size'], PHP_EOL;

How It Works

  1. chdir() makes the relative names refer to the current folder.
  2. symlink() creates hello-link. txt that points to hello.txt.
  3. stat() follows the link and reports the size of hello. txt, which is 13 bytes.
  4. lstat() reports the link itself, whose size is the length of the stored path hello. txt, which is 9.

Frequently Asked Questions

It returns an array of information about a file or symbolic link, including size, owner, permissions and times.
stat() follows symbolic links and describes the target. lstat() describes the link itself.
It returns false and raises a warning. Check the result with === false.
Named keys include dev, ino, mode, nlink, uid, gid, rdev, size, atime, mtime, ctime, blksize and blocks. The same values are also stored under numbers 0 to 12.
PHP caches the result for the same path. Call clearstatcache() if the file may have changed.

Next: mkdir()

mkdir() creates a new folder. You give it a path and, if you like, the permissions and an .

mkdir() 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