PHP ftp_nlist() Function

Beginner
5 min read
Updated: Nov 2026
3 examples
FTP

Definition

In PHP, ftp_nlist() returns a simple list of file and folder names inside a directory on an FTP server.

It is the quickest way to see what is on the server when you only need names. If you also want sizes, types or dates, use ftp_mlsd() or ftp_rawlist() instead.

Syntax

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

PHP
$files = ftp_nlist($ftp, '.');
CallWhat it does
ftp_nlist($ftp, '.')Returns the names in the current remote directory.
ftp_nlist($ftp, '/public_html')Lists a specific remote directory.
ftp_nlist($ftp, '/public_html/*.php')Some servers let you add a pattern, though it is not guaranteed.

Depending on the server, each name may include the directory path, for example public_html/index.php. Use basename() if you only want the last part. Turn on passive mode with ftp_pasv() if the list comes back empty or false.

Library declarations
PHP
ftp_nlist(FTP\Connection $ftp, string $directory): array|false

Parameters

ParameterDescription
ftpRequired. The FTP\Connection object returned by ftp_connect() or ftp_ssl_connect().
directoryRequired. The remote directory to list. Use "." for the current directory.

Return Value

Return ValueDescription
arrayA list of file and folder names. The array is empty if the directory has no entries.
falseReturned on error, for example if the directory does not exist.

PHP Examples

Example 1 — List Files in a Directory

Connect, log in and print every name in the current remote directory.

PHP
<?php
$ftp = ftp_connect('ftp.example.com');
ftp_login($ftp, 'username', 'password');
ftp_pasv($ftp, true);

$files = ftp_nlist($ftp, '.');

foreach ($files as $file) {
    echo $file, PHP_EOL;
}

ftp_close($ftp);

How It Works

  1. ftp_pasv() switches on passive mode so the listing works behind firewalls.
  2. ftp_nlist() returns an array of names for the current directory.
  3. foreach goes through the array one name at a time.
  4. echo prints each name on its own line.

Example 2 — Tell an Empty Directory From an Error

An empty folder gives an empty array, while a missing folder gives false. Check with a strict comparison.

PHP
<?php
$ftp = ftp_connect('ftp.example.com');
ftp_login($ftp, 'username', 'password');
ftp_pasv($ftp, true);

$files = @ftp_nlist($ftp, 'no-such-folder');

if ($files === false) {
    echo "Could not list the directory", PHP_EOL;
} elseif (count($files) === 0) {
    echo "The directory is empty", PHP_EOL;
} else {
    echo count($files), " items found", PHP_EOL;
}

ftp_close($ftp);

How It Works

  1. The folder does not exist, so ftp_nlist() returns false.
  2. The strict comparison === false handles that case first.
  3. An empty array would be caught by the second check with count().
  4. Only a non-empty array reaches the final else branch.

Example 3 — Filter by Extension and Clean the Names

Keep only the PHP files and remove any directory prefix the server adds.

PHP
<?php
$ftp = ftp_connect('ftp.example.com');
ftp_login($ftp, 'username', 'password');
ftp_pasv($ftp, true);

$names = ftp_nlist($ftp, '/public_html') ?: [];

$phpFiles = array_filter(
    array_map('basename', $names),
    fn($name) => str_ends_with($name, '.php')
);

print_r(array_values($phpFiles));

ftp_close($ftp);

How It Works

  1. The ?: [] part gives you an empty array if ftp_nlist() returns false.
  2. array_map('basename', . ..) strips any folder path from every name.
  3. array_filter() keeps only names that end with . php.
  4. array_values() resets the array keys so the output starts at 0.

Frequently Asked Questions

It returns an array with the names of the files and folders in a remote FTP directory.
False means an error, such as a missing directory or a blocked data connection. An empty array means the directory is empty. Try ftp_pasv($ftp, true) if you suspect a firewall.
No, only names. Use ftp_size() for one file, or ftp_mlsd() and ftp_rawlist() to get sizes and dates in a single call.
Some servers return the full relative path. Use basename() to keep only the file name.
ftp_nlist() returns only names, while ftp_rawlist() returns detailed text lines in the format of the server's ls -l command.

Next: ftp_pasv()

ftp_pasv() turns passive mode on or off for an FTP connection. In passive mode, your PHP s.

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