ftp_nlist()

The PHP ftp_nlist() Function

ftp_nlist() returns a flat array of the names of the files and sub-directories inside a directory on an FTP server. It is the FTP equivalent of running the nls/ls command — you get just the names, with no size, permission, or date information.

This page covers the syntax and parameters, a complete working example, what the return value looks like, how to handle failures, the gotchas that trip people up (passive mode, names with no path prefix), and when to reach for ftp_rawlist() instead.

Syntax

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

Return value: an array of names on success, or false on failure.

The returned names do not include the directory prefix — listing /public_html/ gives you index.php, not /public_html/index.php. If the directory is empty, you get an empty array [], which is not the same as false.

A Complete Example

Before you can list anything, you need an open, authenticated connection. The typical flow is ftp_connect() → ftp_login() → ftp_pasv() → ftp_nlist() → ftp_close():

Usage of ftp_nlist()

<?php

// Set up an FTP connection
$conn = ftp_connect('ftp.example.com');
if (!$conn) {
    die('Could not connect to FTP server.');
}

// Login with your FTP credentials
if (!ftp_login($conn, 'username', 'password')) {
    die('Login failed.');
}

// Enable passive mode (often required for directory listings)
ftp_pasv($conn, true);

// Get an array of filenames in the specified directory
$files = ftp_nlist($conn, '/public_html/');

// Output the array of filenames
print_r($files);

// Close the FTP connection
ftp_close($conn);

Each step is guarded: we bail out if the connection or login fails. Enabling passive mode with ftp_pasv() is important — many servers (and most firewalls) require it before a directory listing will succeed, so a missing ftp_pasv() call is the single most common reason ftp_nlist() silently returns false.

For a directory containing two files, print_r() would output something like:

Array
(
    [0] => index.php
    [1] => style.css
)

ftp_nlist() vs ftp_rawlist()

Use the function that matches what you need:

• ftp_nlist() returns just an array of names — perfect for "does this file exist?" or iterating over downloads.
• ftp_rawlist() returns the raw, unparsed LIST output (one string per line, like ls -l), which includes sizes, permissions, and dates — useful when you need that metadata and are willing to parse it.

If you only need names, prefer ftp_nlist(): its output is consistent across servers, whereas the format of ftp_rawlist() varies by FTP server type.

Error Handling

It's important to handle errors properly when using the ftp_nlist() function. If the function returns false, it means that the listing was unsuccessful. Note that an empty directory returns an empty array [], not false. Here's an example of how to handle errors:

Error handling in ftp_nlist()

<?php

// $conn is assumed to be established from the previous example
$file_list = ftp_nlist($conn, '/public_html/');

if ($file_list === false) {
    echo "Failed to list directory on remote server.\n";
}

ftp_close($conn);

Always compare with === (strict equality). Using a loose if (!$file_list) would treat a legitimately empty directory ([]) as an error, since an empty array is falsy in PHP.

Common Gotchas

• Forgetting passive mode. Call ftp_pasv($conn, true) after logging in if listings return false.
• Empty array vs false. [] means "directory exists but is empty"; false means the listing failed. Distinguish them with ===.
• Names have no path. Prepend the directory yourself when you need a full path: $dir . '/' . $name.
• Hidden files. Some servers omit dot-files (.htaccess) from ftp_nlist(). Pass -a via the directory argument (e.g. '-a /public_html/') on servers that support it.

Conclusion

ftp_nlist() is the simplest way to get the names of files in a remote directory. Pair it with ftp_pasv() for reliability, check the return value with ===, and reach for ftp_rawlist() when you also need file metadata. For the full FTP workflow, see the PHP FTP overview.

Practice